F03/08 supporting Documentation tools

[Izaak B Beekman]

I know from some google searches that this topic has been discussed in
the past, but couldn't really get a good feel for the pros and cons of
the different documentation tools.

There is a pretty good list of those auto-documentation tools which
support Fortran on the fortran-wiki:
http://fortranwiki.org/fortran/show/Automatic+documentation

I'm specifically interested in support for F03 and F08 features like
over-loaded TBPs, but I don't really know how much mileage I'm going to
get here. I'd love to hear peoples opinions and experiences using these
tools.

Right now, FORTRANDOC seems like a nice compromise between the
flexibility (but verbosity and extra work) of ROBODOC and the
simplicity of something like f90doc. However, I am nervous about how
buggy it could be and whether it will continue to be actively
maintainted.

All suggestions and insight most welcome.
--
-Zaak

[Ian Harvey]

I use doxygen. I'm not totally happy with it because some of the newer
features of the language still confuse it a little, plus in recent
versions its mapping of Fortran language concepts like modules, generic
interfaces and procedure bindings across to what someone thought was the
nearest equivalent concept in other language models has been a bit
wacky, though there is also the possibility that this user is the wacky
one and he simply needs to spend a bit more time experimenting.

I guess these changes indicate that other Fortran users exist and are
perhaps participating in its development.

Because of the sunk cost of my existing documentation I would like to
spend some time one day (more likely, one month or one quarter) beating
things into the shape I think they should be. But at the rate I am
going I doubt I will have the time to do that for another 3.14 decades.
Plus the front end fortran scanner uses that flex thing which I know
zip about.

Anyway, the code I document using that tool uses lots of F2003 stuff.
Sometimes I even read that documentation.

[DanielH]

I would also be interested in experiences. Did you try FortranDOC?

[Izaak B Beekman]

On 2014-06-03 13:56:19 +0000, DanielH said:

> I would also be interested in experiences. Did you try FortranDOC?

I've been in contact with the FortranDOC author, Stefano Zaghi, and it
seems he no longer uses or maintains this tool; his projects on his
website are outdated, but ARE up to date on GitHub. He has switched to
Doxygen for his documentation purposes, after Doxygen added better
Fortran support.

Right now, I am choosing between doxygen and ROBODoc. The output of
Doxygen baffles me a bit, I find that top menu a bit unintuitive and
prefere the layout of ROBODoc. However, it seems like Doxygen has some
built in scanning capabilities, whereas ROBODoc pulls everything from
your comments and is language agnostic. This could be a pro or a con of
ROBODoc. I still haven't made up my mind, but have seen Fortran
projects using both. For example checkout Stafano Zaghi's
https://github.com/szaghi/Lib_VTK_IO for an example using Doxygen (you
can also find the generated output in a link in the README.md) and
Jacob Williams' https://github.com/jacobwilliams/json-fortran JSON I/O
library. (However the documentation is not available online for the
latter, you would have to download ROBODoc and run it, to generate the
docs.) If you want to get a look at the ROBODoc formatting/etc. you can
checkout the ROBODoc homepage (http://rfsber.home.xs4all.nl/Robo/) and
look at the examples section, too.


--
-Zaak

[wordweb...@googlemail.com]

A freelancer recently made a F2003 documentation script for me since none of the standard ones seemed to do quite what I want. It includes basics, and also shows nice inheritance trees - for example output see

http://cosmologist.info/cosmomc/doc/file_GeneralTypes.f90.html
http://cosmologist.info/cosmomc/doc/

Quite a few things could be improved though, and it does not support all fortran syntax, but the source is freely available on github

https://github.com/cmbant/fordocs

[Stefano Zaghi]

Dear all,

I would like to point out a new project (not mine) for modern fortran documentation that, in my opinion, overtakes all other tool:

https://github.com/cmacmackin/ford

This project is very young, but already great! I am migrating from doxygen to it for several reasons... among them:
1. it is tailored to modern fortran, thus:
+ derived type, interface, type bound procedures.... well supported;
+ driven by markdown;
+ support github flavored markdown syntax;
+ the default output is extremely clear;
+ easy output customization even with very basic css knowledge;
2. the author, https://github.com/cmacmackin , is great!

Presently two of mine free projects are using ford:
http://szaghi.github.io/Lib_VTK_IO/index.html
http://szaghi.github.io/FLAP/index.html

My best regards

[Wolfgang Kilian]

On 11.01.2015 10:50, Stefano Zaghi wrote:
> Dear all,
>
> I would like to point out a new project (not mine) for modern fortran documentation that, in my opinion, overtakes all other tool:

Well, that depends. The useful part is automatic generation of a
module/type/procedure hierarchy index etc., that would indeed be
welcome. Does the tool generate dependencies for Makefiles etc.? I
don't see this in the feature list, although this appears to be
straightforward once the tool has digested a program package.

Unfortunately, the author requires the programmer to follow a philosophy
of 'documentation is part of the code'. Comment lines must always
follow the declarations to which they belong. Some people like this,
some don't.

If the programmer adheres to a convention where code is part of the
documentation (Literate Programming, with tools such as web/noweb for
extracting the code), documentation naturally comes before code. Then,
the tool appears to be less useful. It would be ideal to combine both
approaches.

> https://github.com/cmacmackin/ford
>
> This project is very young, but already great! I am migrating from doxygen to it for several reasons... among them:
> 1. it is tailored to modern fortran, thus:
> + derived type, interface, type bound procedures.... well supported;
> + driven by markdown;
> + support github flavored markdown syntax;
> + the default output is extremely clear;
> + easy output customization even with very basic css knowledge;
> 2. the author, https://github.com/cmacmackin , is great!
>
> Presently two of mine free projects are using ford:
> http://szaghi.github.io/Lib_VTK_IO/index.html
> http://szaghi.github.io/FLAP/index.html
>
> My best regards
>

-- Wolfgang

--
E-mail: firstnameini...@domain.de
Domain: yahoo

[Stefano Zaghi]

Il giorno lunedì 12 gennaio 2015 10:41:21 UTC+1, Wolfgang Kilian ha scritto:
> On 11.01.2015 10:50, Stefano Zaghi wrote:
> > Dear all,

> Well, that depends. The useful part is automatic generation of a
> module/type/procedure hierarchy index etc., that would indeed be
> welcome. Does the tool generate dependencies for Makefiles etc.? I
> don't see this in the feature list, although this appears to be
> straightforward once the tool has digested a program package.

If you are searching for an automatic building tool, you can try:

https://github.com/szaghi/FoBiS

FoBiS.py can be easily coupled with Ford (https://github.com/szaghi/Lib_VTK_IO/blob/master/fobos lines 132+). Anyhow, an integration between them is straightforward (FoBiS.py is currently under refactoring to be more modular).

> Unfortunately, the author requires the programmer to follow a philosophy
> of 'documentation is part of the code'. Comment lines must always
> follow the declarations to which they belong. Some people like this,
> some don't.

Is is not strictly required to use only docstrings. It is possible to include external markdown files containing documentation (see https://github.com/szaghi/Lib_VTK_IO/blob/master/src/Lib_VTK_IO.f90 lines 4 and 8). Indeed, Ford is designed to build docs from docstrings, but it not limited to this approach. Obviously, the "Literate Programming" is not the design specification of Ford.

In my opinion, Ford presently offers a better support to Fortran with respect of Doxygen/robodoc. It is only an opinion on the tool, not on the phylosophy behind the programming style.

My best regards.

P.S. I am a supporter of docstrings approach of course :-)

[Wolfgang Kilian]

On 01/12/2015 01:35 PM, Stefano Zaghi wrote:
> Il giorno lunedì 12 gennaio 2015 10:41:21 UTC+1, Wolfgang Kilian ha scritto:
>> On 11.01.2015 10:50, Stefano Zaghi wrote:
>>> Dear all,
>> Well, that depends. The useful part is automatic generation of a
>> module/type/procedure hierarchy index etc., that would indeed be
>> welcome. Does the tool generate dependencies for Makefiles etc.? I
>> don't see this in the feature list, although this appears to be
>> straightforward once the tool has digested a program package.
>
> If you are searching for an automatic building tool, you can try:
>
> https://github.com/szaghi/FoBiS
>
> FoBiS.py can be easily coupled with Ford (https://github.com/szaghi/Lib_VTK_IO/blob/master/fobos lines 132+). Anyhow, an integration between them is straightforward (FoBiS.py is currently under refactoring to be more modular).
>

Thanks for the link - interesting project.

Incidentally, we do use the autotools chain for our project - it is very
powerful and, in particular, libtool does wonders in a heterogeneous
system with a complex package structure -- no reason for reinventing the
wheel there. On the user's side, it doesn't require any packages beyond
Unix core tools and Make. What I would like to improve is a more
seamless integration of the Fortran dependency generator and a
doxygen-like tool for documenting modules, types etc. in addition to the
existing doc/code integration.

>> Unfortunately, the author requires the programmer to follow a philosophy
>> of 'documentation is part of the code'. Comment lines must always
>> follow the declarations to which they belong. Some people like this,
>> some don't.
>
> Is is not strictly required to use only docstrings. It is possible to include external markdown files containing documentation (see https://github.com/szaghi/Lib_VTK_IO/blob/master/src/Lib_VTK_IO.f90 lines 4 and 8). Indeed, Ford is designed to build docs from docstrings, but it not limited to this approach. Obviously, the "Literate Programming" is not the design specification of Ford.
>
> In my opinion, Ford presently offers a better support to Fortran with respect of Doxygen/robodoc. It is only an opinion on the tool, not on the phylosophy behind the programming style.
>
> My best regards.
>
> P.S. I am a supporter of docstrings approach of course :-)
>

Yes, one could combine different approaches.

-- Wolfgang

[Rafik Zurob]

"Wolfgang Kilian" wrote in message news:m90vlm$i20$1...@dont-email.me...

>
>On 01/12/2015 01:35 PM, Stefano Zaghi wrote:
>> Il giorno lunedì 12 gennaio 2015 10:41:21 UTC+1, Wolfgang Kilian ha
>> scritto:

>>> [...] Does the tool generate dependencies for Makefiles etc.? I

>>> don't see this in the feature list, although this appears to be
>>> straightforward once the tool has digested a program package.
>>
>> If you are searching for an automatic building tool, you can try:
>>
>> https://github.com/szaghi/FoBiS
>>
>> FoBiS.py can be easily coupled with Ford
>> (https://github.com/szaghi/Lib_VTK_IO/blob/master/fobos lines 132+).
>> Anyhow, an integration between them is straightforward (FoBiS.py is
>> currently under refactoring to be more modular).
>>
>
>Thanks for the link - interesting project.

Another thing to note is that several Fortran compilers can generate
makefile dependencies for you. I know IBM XL Fortran (which I work on) and
gfortran do. A Google search shows that Intel Fortran Composer does as
well. One advantage of using the compiler to generate dependencies is that
the compiler knows about the newer Fortran features it supports. For
example, when we added submodule support to XL Fortran, we updated our
makefile dependency code to take submodules into consideration. If I had
mod.f containing a module definition containing a separate module
subroutine, submod.f containing the definition of the separate module
subroutine and a declaration of a separate helper function, submod2.f
containing a submodule containing the definition of the separate helper
function, and program.f containing a program that uses the module, the
compiler would generate the following dependencies:

mod.o m.mod: mod.f
submod.o m_s.smod: m.mod submod.f
submod2.o m_s2.smod: m_s.smod submod2.f
program.o: m.mod program.f

Our compiler knows that it generates *.smod files for submodules and that
these files are only needed when extending the submodules. A third party
tool might not know this.

Rafik

[FortranFan]

I wonder how many readers of this post think like me that documentation tools should focus on documentation generation and that makefiles is a separate realm altogether!

[Wolfgang Kilian]

Great!

Namely, the implementation of submodules. With the small caveat that
our usual target machines are x86(64) based - and we have to support
more than one compiler, anyway.

Regarding dependency generation: I like this approach because
dependency generation is part of the build process. Or, that's the way
it is intended in the autotools context. Just to make sure that all of
our (present and future) target compilers support such a facility, in a
reasonably compatible way.

[Wolfgang Kilian]

That wasn't my intention.

Probably I may state it this way: personally, I'm interested in tools
that add functionality to (can be easily integrated in) a proven build
system (autotools, cmake, or whatever), ideally all of them. Both
executable code and doc are targets of a build. Designing a new build
system from scratch is an ambitious task.

[Stefano Zaghi]

I prefer KISS small tools tailored for a small set of goals rather than monster tools able to do everithins.

From my point of view, Ford is great because it has one goal: build doc of ONLY Fortran codes. Doxygen/Robodoc & Co. are great tools, but their aim to support a wide set languages reflects a minor support of Fortran with respect Ford.

Similar consideration can be made for FoBiS/code as the ones made for Ford/doc: an autotool able to build everithings is not my preferred aproach.

This make the development of build tools from scratch less complex: just select a small set of goals and do them at the best.

Ford, presently support a wider range of Fortran specifications than doxygen, and Ford at its first steps in the world. This for me is an evidence that KISS is better than complex.

As the usage of compilers builtin analyzers (for support new features and dependencies), you are not completely convinced me. Compiker vendors are not often compliant with the standards, almost all of them are not free. There is GNU gfortran you say... well its support to f2003/2008 is very poor with respect others (intel/ibm for example). Consequently, you must choice which compiler use, but which is the best? GNU is free, but XLF is great, intel is very good, but not free...

No, relay on ONE compiler for other than compiling is not the better way for me. I prefer to rely on the standard specifications and develop a KISS free tool for build doc/code and use the compiler just for compiling.

See you soon.

[Wolfgang Kilian]

On 14.01.2015 07:20, Stefano Zaghi wrote:
> I prefer KISS small tools tailored for a small set of goals rather than monster tools able to do everithins.

If I have a Fortran-only project that I'm certain about not growing
beyond limits, yes, I'd also rather use a lightweight build tool.

Unfortunately, successful program packages tend to grow, and eventually
contain a mixture of modern Fortran, FORTRAN, C, C++, Python, or
whatever code, some precompiled, some built from source, some as
subpackages with their own build structure, on-the-fly compiling,
dynamic linking, and so on. And still, the program has to compile and
run on a variety of different architectures. Simply for this reason, I
have started to become comfortable with monsters like autotools.

> From my point of view, Ford is great because it has one goal: build doc of ONLY Fortran codes. Doxygen/Robodoc & Co. are great tools, but their aim to support a wide set languages reflects a minor support of Fortran with respect Ford.

And I fully agree, doxygen is not suited for Fortran. Therefore I'd
very much like to use a better tool such as Ford; it just has to fit in
an existing complex code and build structure. So it should impose as
few conventions on the programmer as possible. I guess that this
situation is not unusual.

> Similar consideration can be made for FoBiS/code as the ones made for Ford/doc: an autotool able to build everithings is not my preferred aproach.
>
> This make the development of build tools from scratch less complex: just select a small set of goals and do them at the best.

Yes, if it is sufficient for the real use case.

> Ford, presently support a wider range of Fortran specifications than doxygen, and Ford at its first steps in the world. This for me is an evidence that KISS is better than complex.
>
> As the usage of compilers builtin analyzers (for support new features and dependencies), you are not completely convinced me. Compiker vendors are not often compliant with the standards, almost all of them are not free. There is GNU gfortran you say... well its support to f2003/2008 is very poor with respect others (intel/ibm for example). Consequently, you must choice which compiler use, but which is the best? GNU is free, but XLF is great, intel is very good, but not free...
>
> No, relay on ONE compiler for other than compiling is not the better way for me. I prefer to rely on the standard specifications and develop a KISS free tool for build doc/code and use the compiler just for compiling.

Completely agree. Those things probably won't be standardized.

I'd be comfortable if the functionality was available in all target
compilers. The configure process always can deal with differences in
the implementation.

> See you soon.

[Anton Shterenlikht]

Wolfgang Kilian <kil...@invalid.com> writes:

>And I fully agree, doxygen is not suited for Fortran. Therefore I'd

Please elaborate.
I looked at doxygen, found it too complex to learn
and settled on robodoc. But I'd like to hear your
reasons for dismissing doxygen. A lot of colleagues
push me towards it, so would be good to know an
informed opposite opinion.

Thanks

Anton

[Wolfgang Kilian]

Maybe I'm ill-informed, but does doxygen support Fortran TBP,
type-extension hierarchies, modules, abstract types, interfaces, and so on?

These structures have things in common with C++ structure elements, for
which doxygen is designed, but are they supported?

[Stefano Zaghi]

@Anton

Doxygen is great. I used it with Fortran for some years. However, it is not tailored for Fortran. As Wolfgang said, some specific Fortran structures are not supported by default. For giving you a real example see this http://szaghi.github.io/OFF/d4/d13/group__Data__Type__AMRBlockDerivedType.html. The type bound procedure "init" is identified just as public member of the derived type, not a type bound procedure. Moreover, to obtain a "Fortranish" API description, you have to "pollute" your docstrings for driving doxygen to the right way, e.g. https://github.com/szaghi/OFF/blob/master/src/OFF.f90 from line 1 to 31. On the contrary a tool like Ford designed for Fortran do this effortless. Moreover, the support for Fortran specific structures is better, see this http://szaghi.github.io/Lib_VTK_IO/type/type_vtk_file.html.

This is my experience. Of course, doxygen/robodoc are mature tools plenty of features, but they are not KISS as Ford. For migrating Lib_VTK_IO from doxygen to Ford I use few hours, whereas the initial setting of doxygen was not so easy.

My best regards.