sphinx autodocumentation for fortran code

[Mark Andrews]

Hello,
I am new to this group. I have a quick question. I write a lot of
mixed fortran+python code, i.e. called external fortran modules using
f2py. I use sphinx for the documentation of the python (obviously),
but would like to do the same with the fortran code and then have
everything available a single project on a sphinx generate html manual
website. I presume this can be done by writing an extension. In fact,
I think something like this already exists:
http://www.ifremer.fr/vacumm/library/sphinxext.fortran_autodoc.html

I have a bit of trouble following this, as my French is not too good.
Does anyone know about this extension and whether it works? Otherwise,
does anyone know of other fortran autodocumentation extensions for
sphinx?

many thanks,
-m

[Steph]

Hi,

I'm the author of this extension.
In fact, there are two extensions :
- One for documentation fortran code manually : a sphinx "domain".
- One usinf f2py and some hacks to generate documentation using the
first extension.
Here is an example : http://relay.actimar.fr/~raynaud/enkfplatform/

It all but stable and complete, that's why it's a bit hidden on the
net!
And in fact, I don't have much time to work on it right now, and
publish it at the same place as other sphinx extensions.
If someone is interested spending some time to improve it...

However, I can help you setting up sphinx for using using the current
version.
In a few words, you can do it in two steps :
- Set the fortran_src configuration variable to a list (or glob) of
absolute path to you fortran code (list of files, glob like *.f90,
directories, etc).
- Call the approritate directives, like : .. f:fautomodule: modulename

[mparsani]

Dear Stephane,

thanks for writing this extension.

Could you please give us some informtion with the installation?

I want to install sphinxext, so I run: python setup.py --with-sphinxext

but I get the error: 

--with-sphinxext not known.

Then, when I check the simple installation of vacumm.misc by typing python -c "import vacumm.misc"

I get the following error:

 File "...../Library/Python/2.7/lib/python/site-packages/vacumm/misc/misc.py", line 49, in <module>

    import numpy as N,MV2,cdtime

ImportError: No module named MV2

Thanks in advance!

[Stephane Raynaud]

Hi,

in fact, you don't need to install the VACUMM package to use these fortran extensions.
I just extracted them from VACUMM and built a simple package:
  http://relay.actimar.fr/~raynaud/sphinxfortran-0.1.tar.gz
Both extensions will be accessible under the "sphinxfortran" package.

Tell me if it works.

[German Salazar]

So, I just came in need of something like this...will somebody be so kind as to post some Fortran source files that include documentation in reStructuredText....in fact, I am still in doubt on how exactly sphinx and this extension can be used...

thanks...hope somebody sees this...there has not been activity in 2 years. 

gsal 

[Stephane Raynaud]

This package is part of the VACUMM package,
and its documentation has been translated to english :
http://relay.actimar.fr/~raynaud/vacumm/user.desc.fdoc.html

I just made a new extraction and created a distribution file:
 http://relay.actimar.fr/~raynaud/sphinxfortran-0.2.tar.gz
All the other sources (like on github) are just forks of old versions,
and are not up-to-date.

The package is made of an extension that add the fortran domain support to sphinx,
and of another extension that allows autodocumenting fortran codes.
As explained in the documentation, you basically need to add
your fortran file paths to the fortran_src variables in the conf.py file,
then you include directives to your rst files to insert
auto-documentation of files, modules, routines, etc.

[German Salazar]

Stephane: 

Thanks for such quick reply. 

I am afraid I still don't quite understand or it is not what I had in mind. Nothing wrong with it, I do want to learn reStructuredText and write documentation with it...but it looks like I need to duplicate information...once inside the Fortran source as usual and once again in the rst files for sphinx.

A long time ago, I used robodoc...I simply added minimal markers inside my Fortran sources and robodoc created html with the information inside the Fortran sources...I did not need an index file or any other file with documentation outside the Fortran source files.  Granted, it was limited in that it only took text...no markdown, no latex, no formulas; but it was very useful, nevertheless; also, it was not a documentation manual at all but just basically an API...but I only had to type the information once inside the Fortran source and that's it.

With this sphinx based tool...it seems to me that I don't add anything to the Fortran source files; instead, I simply create a whole new file separate from the sources...is this correct?   If so, this is not quite what I had in mind...I was looking for something more along the lines of how docstrings in Python are used by sphinx to add to the documentation out of the python sources themselves without having to duplicate explanations...is it possible to do the same thing with Fortran?   If so, how would an annotated Fortran source look like?  The link provided about the fortran domain seems to show what goes inside the *.rst files but makes no mention of what goes inside the Fortran files. 

Thanks, again. 

gsal

[Stephane Raynaud]

Yes, you first need to integrate it in a sphinx doc with some rst file.
In addition, there is also a support of "fortran docstrings": http://relay.actimar.fr/~raynaud/vacumm/user.desc.fdoc.auto.html#optimize-the-process
The documentation is quite limited on this aspect, especially for subroutine docstrings.
In their case, it assumed that docstring have the following generic format:

! General description
!
! :Params:
!     - **param**, (shape) [float,in] :: Param description.
!
! :Foo: Bar

Usually, the params and options sections are filled automalically and placed as the first sections.
If some parameters are manually described in the docstring, their describtion is updated.
Other sections are created, like in these examples:
http://relay.actimar.fr/~raynaud/vacumm/user.desc.fdoc.dom.html#f/special_stats

[German Salazar]

Hhhhmmm...I seem to be getting somewhere...

Managed to create html docs and even though the make html command gives feedback of analyzing the fortran sources, it is not picking up any of the docstrings from the fortran sources.  

Any idea as to what might be happening?  

[German Salazar]

By the way, the link above to the sphinxfortran extension is labeled as being version 0.2...but the actual file downloaded ended up being version 0.1...is that o.k.?

O.k., as only did as indicated in the README file and added just one line to the create index.rst file:

Contents:

.. toctree::
   :maxdepth: 3

.. f:automodule:: gasprop

I get the following messages during make html: 

loading translations [fortran]... not available for built-in messages

and later on:

reading sources... [100%] index                                                                                           

Exception occurred:

  File "/home/salazag/local/programs/anaconda/lib/python2.7/site-packages/sphinxfortran/fortran_domain.py", line 263, in scan_fieldarg

    raise ValueError('Wrong field (%s). It must have at least one parameter name and one argument'%fieldname)

ValueError: Wrong field (). It must have at least one parameter name and one argument

The full traceback has been saved in /tmp/sphinx-err-E3hM6g.log, if you want to report the issue to the developers.

Please also report this if it was a user error, so that a better error message can be provided next time.

gsal

[German Salazar]

O.k., getting somewhere...tried different combinations and permutations and I am now able to process entire files at a time. 

It turns out that the directives are not really interchangeable. 

For the *main* program, i.e., the one that has the program pname procedure in it, one must use the  .. f:autoprogram:: pname directive. Nothing else works; not even attempting .. f:autosrcfile:: pname.f90 works for this particular file. 

For source files containing modules, one must use the .. f:automodule:: modname directive; and modname needs to be all lower case even if written in upper- or camel-case in the Fortran files. No point on using the .. f:autosrcfile:: modname.f90 with this file, it does not work. 

"Regular" Fortran source files, i.e., not containing the main procedure or modules but just other functions and subroutine can be auto-documented with the src directive .. f:autosrcfile:: filename.f90

Variables are being picked up but their in-line descriptions are not being brought over. Would like to get this working. 

--
You received this message because you are subscribed to a topic in the Google Groups "sphinx-users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-users/gQfMxDsXQo0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to sphinx-users...@googlegroups.com.
To post to this group, send email to sphinx...@googlegroups.com.
Visit this group at http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

[Masood Azizi]

Hello, I am also trying to generate auto documents by Sphinx on fortran codes. I could add fortran extensions to Sphinx and successfully run $ make html. But the output is only the program name in document.

 I have used f:autoprogram directive in index.rst. Further details are in the following:

My program tree is like this:

├── doc
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   ├── _static
│   └── _templates
└── project 

    └── caf10.f 

conf.py includes:

sys.path.insert(0, os.path.abspath("../project/caf10.f"))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'vacumm.sphinxext.fortran_domain',
    'vacumm.sphinxext.fortran_autodoc'
]

fortran_src = [
    '/home/Documents/fortran-sphinx/project/caf10.f'
]

index.rst contains:

Documentation for the Code
**************************

.. f:autoprogram:: caf10

Contents:

.. toctree::
:maxdepth: 2 

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Fortran program is something like:

C Handling system components

      PROGRAM caf10
      IMPLICIT NONE

      INTEGER NOERR, NSCOM, I
      CHARACTER FNAME*12, SCNAME*24

C Initialise program 
      CALL TQINI(NOERR)

      FNAME = 'cosi.dat'

C Open cosi.dat (system C-O-Si)
C for reading
      CALL TQOPNA(FNAME, 10, NOERR)

C Read data-file 
      CALL TQRFIL(NOERR)

C Close data-file 
      CALL TQCLOS(10, NOERR)


C Print the names of all system components
      WRITE(*,FMT='(A)') 'Names of system components:'

      DO I=1, NSCOM
         CALL TQGNSC(I, SCNAME, NOERR)
         WRITE(*,FMT='(I2,A)') I, ': ' // SCNAME
      ENDDO

      END

I don't have module or function definition in these fortran programs. I want to highlight the codes and comments, use cross references, and print the output of each method into the documentation.

The output of generated document is just the program name, and nothing else is included in the documentation:

program caf10

By running make html, it logs no error:

$ make html    

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.2.3
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/objects.inv...
parsing fortran sources... done
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
test1ng sources... [100%] index                                                                                                                        

/home/masood/Documents/fortran-sphinx-2/doc/index.rst:4: WARNING: test2
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                         
writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 1 warning.

Do you have any idea how can I make a document which parsed the program, highlighted commands, included comments, and added cross references?

[Masood Azizi]

We don't have module or function definition in these fortran programs. We want to highlight the codes and comments, use cross references, and print the output of each method into the documentation.

[Masood Azizi]

[German Salazar]

Well, as you can see from my postings, I myself had to do lot of trial and error..you may have to do some of that yourself until sphinx starts finding what it needs to find. 

I see that in your conf.py you have 

sys.path.insert(0, os.path.abspath("../project/caf10.f"))

but that is not a path!....that's a filename...try:

sys.path.insert(0, os.path.abspath("../project"))

instead.  Or, you may be able to forget about sys.path and insated specify

fortran_src=['../project']

fortran_ext=['f']

Also, I have no idea how you installed this extension; but in my case, as I am not part of the vacuum project, I don't write vacuum when specifying the new extension/domain:

extensions = [

    'sphinx.ext.autodoc',

    'sphinx.ext.todo',

    'sphinx.ext.mathjax',

    'sphinxfortran.fortran_domain',

    'sphinxfortran.fortran_autodoc',

]

When I installed the software into my own installation of Python, I noticed its name issphinxfortran and, so, that is what I used...it is not sphinxext, like you have. 

Hope this helps. 

gsal