As far as I can see, https://fortran-lang.org/packages/programming only lists one documentation tool, FORD (https://github.com/Fortran-FOSS-Programmers/ford), which using the words of his creator is “in a pretty deep coma” (FORD issue #317): despite 67 open issues and 17 pull requests, the last commit is dated 15 months ago. This lack of maintenance discourages its adoption.
What are the alternatives for documenting Fortran code in a robust, sustainable way? I am particularly interested in generating documentation that is mathematically rich, and that would benefit from diagrams and links to research articles.
In case the answer is Doxygen:
FORD’s documentation states that it was written “due to Doxygen’s poor handling of Fortran”. Could somebody be more specific, and describe the issues with Doxygen’s handling of Fortran?
I’ve read that Doxygen allowing rich text via Markdown rather than reST makes it less powerful than Sphinx, and that there seems to be ways of inserting reST in Doxygen comments and produce Sphinx documentation via Doxygen XML output -> some tools (Breathe?) -> Sphinx. Would this work for a Fortran code?
Is FORD-ready code compatible with Doxygen or vice-versa?
Doxygen’s treatment of Fortran is not so bad for Fortran 90 code. However, based on my experience, problems start to emerge when there is a Fortran 2003 OOP code or Fortran 2008 features like submodule. If people continue using it, then one can hope to see the new features of Fortran being supported in the future as well.
I cannot speak of other Fortran documentation tools. However, I can attest that the document preparation with and syntax of Doxygen is relatively straightforward and powerful enough to achieve my goals. Compared to the sphinx, I like Doxygen’s syntax and find it more appealing and easier to implement. Equations are also easy to implement and follow the syntax of LaTex.
I wouldn’t necessarily call it resumed, but it is certainly stirring. @rouson managed to work out a deal with the author and contracted him to fix a bug or two that was impacting some of our projects. We intend to continue to work with him when anything is impacting us, and hope to urge it back into active development. Any help in that endeavor that anyone can provide would be greatly appreciated.
Actually, I see that a new maintainer took over, and dozens of issues and PRs have been handled, and a new release is coming up! See the discussion in issue #317.
So I’m optimistic and perhaps it would be nice that this would motivate new people to join the endeavor.
That is great; been hesitant to make much use of Ford because I was not sure how long it might be around.
I was hoping “somehow” the AST capabilitites of LFortran (which have come a long way from what I just saw trying out the “lfortran fmt” feature ) could be merged with Ford to reduce the duplicate efforts of parsing Fortran; but had not looked into how feasible that was, just “it seems it would make sense if …” thought.
Even better. Issues like this concerning Fortran not providing a standard-supported method of generating external documentation from source files are why I use an agnostic approach to documentation with preprocessing where I allow for any type of flat text to be placed in the source file (input for Ford, Doxygen, txt2man, Latex, HTML, markdown). I planned on making a converter from txt2man markdown to Ford and Doxygen format, which are similar enough so I could use all three with the same flat text input but Ford is quite appealing (albeit I still need man-pages in particular) if it is actively supported. Had no idea that using the LFortran AST was already being considered for leveraging by Ford. Great!
