Automatic Documentation Generator for Source File

[Robert]

I would like to hear what positive or negative reviews people can give for source file "automatic" documentation generators.  What program do you recommend that I give a try.  I see that there is FORD, Doxygen, Sphinx-Fortran, ROBODoc, Fortrandoc and others.  Your suggestions are appreciated.  Thank you.

[FortranFan]

I have personally found FORD to be adequate, for the challenge often is not automatic generation, rather the authoring of good content itself that often gets overlooked amid all the focus on the mechanics.

Nonetheless, I will strongly suggest you ask this question on the Fortran Discourse here: https://fortran-lang.discourse.group/ that can help you gain broader feedback from the Fortran community.

[Daniel_Dopico]

I abandoned doxygen because I does not support submodules and apparently they are not working on Fortran very much.
I tried to move to FORD but it is "in deep coma" (they are not supporting it) and it does not understand my code, it simply crashes when reading some parts of it.
I feel like there is nothing for documenting Fortran code.

[Arjen_Markus]

Would it be possible for you to share the code (or samples of code) that cause FORD to crash? As part of the Google Summer of Code project we are thinking of reviving FORD =, so this might be a good use case (*).

(*) See https://fortran-lang.discourse.group/t/fortran-monthly-call-january-2021/557

[DavidWhite]

Is FORD only available in Linux implementations or is there a Win version?

[Arjen_Markus]

It is a Python-based package, so I went ahead installing it via github and then installing the packages that it requires. But I get stuck with graphviz, oddly enough.

[Arjen_Markus]

Okay, FORD requires gfortran to preprocess the source code, so I switched to Cygwin to get it to work. And then it worked fine on the example.

[Daniel_Dopico]

Sorry for the delay with this. I include here a code crashing with FORD. 

[Arjen_Markus]

Ah, thanks. I will have a look, though I do not maintain it in any way ;).

[jimdempseyatthecove]

Modern (aka auto-generated) documentation sucks. At least that is in my opinion. In many cases, it now requires you to have multiple copies of the documentation open in different places to make sense (unless  you have an eidetic memory).

Jim Dempsey

[Johannes_Rieke]

I work with Doxygen, which I found in most cases a good choice for Fortran. Unfortunately, there is no support for submodules currently as far as I know.

I shortly tested FORD and I think it's the best suited auto-documentation tool currently. However, I found no time to change the already existing Doxygen headers/tags in my many source files. For new code definitely a good choice.

Sphinx I use for Python but not Fortran. For Python I find it personally compared to Doxygen much more time consuming to get the same results - a lot of extra work is needed and you still need some extra modules. Maybe I'd not spent enough time in reading the documentation... But it's clearly no quick solution. I have no idea whether the Fortran extension is better in this regard. As Doxygen Sphinx has not been developed directly for Fortran.

[DavidWhite]

I have used RoboDoc for many years.

It is open source, and works well, but I gather that the original developer is no longer actively supporting it.

As in FortranFan's reply, the key is in discipline and good commenting of the code.  If you have discipline, always comment new code when you add it, and when you modify it, then it is possible to end up with some good documentation.

If you're a single developer, then it is easy - no one to blame but yourself if the documentation is not up to date.  In a team, then as long as everyone plays ball, you should be able to make it work.

[DavidWhite]

The main developer of RoboDoc Frans Slothouber has restarted development recently.

I suggest that you visit https://rfsber.home.xs4all.nl/Robo/

RoboDoc is open source, so that if it does not adequately accommodate submodules, these can be added.

I'm not sure how "automatic" you want the documentation to be -- do you expect plain vanilla Fortran to produce documentation?

I have for many years embedded documentation in my code using the RoboDoc markup code.  This requires some diligence in setting up new code, but it is a discipline that we should all follow.

RoboDoc produces a number of output formats.