Community
cancel
Showing results for 
Search instead for 
Did you mean: 
Robert
Beginner
716 Views

Automatic Documentation Generator for Source File

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.

0 Kudos
12 Replies
FortranFan
Honored Contributor II
697 Views

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
Novice
458 Views

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
Valued Contributor III
367 Views

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
Black Belt
346 Views

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

Arjen_Markus
Valued Contributor III
335 Views

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
Valued Contributor III
331 Views

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
Novice
242 Views

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

Arjen_Markus
Valued Contributor III
233 Views

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

jimdempseyatthecove
Black Belt
662 Views

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

Tags (1)
Johannes_Rieke
New Contributor III
638 Views

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
Black Belt
605 Views

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
Black Belt
437 Views

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.

Reply