# Documentation tools for Fortran codes **URL:** \ **Category:** Help\ **Created:** [November 18, 2020, 4:18pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428 "2020-11-18T16:18:19Z")\ **Posts on this page:** 11\ **Page:** 1
**Author:** ![jme52](https://avatars.discourse-cdn.com/v4/letter/j/c4cdca/32.png) [@jme52](https://fortran-lang.discourse.group/u/jme52)\ **Post date:** [November 18, 2020, 4:18pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/1 "2020-11-18T16:18:19Z")
As far as I can see, [https://fortran-lang.org/packages/programming](https://fortran-lang.org/packages/programming) only lists one documentation tool, FORD ([https://github.com/Fortran-FOSS-Programmers/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. 1. 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: 1. 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? 2. 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? 3. Is FORD-ready code compatible with Doxygen or vice-versa? ---
**Author:** ![shahmoradi](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/shahmoradi/32/3151_2.png) [@shahmoradi](https://fortran-lang.discourse.group/u/shahmoradi)\ **Post date:** [November 19, 2020, 5:55pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/2 "2020-11-19T17:55:44Z")
1. 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. 2. 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. Here is an example: [https://www.cdslab.org/paramonte/notes/api/kernel/index.html](https://www.cdslab.org/paramonte/notes/api/kernel/index.html) The preparation of this entire documentation using Doxygen took 2-3 days to complete. ---
**Author:** ![pcosta](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/pcosta/32/5504_2.png) [@pcosta](https://fortran-lang.discourse.group/u/pcosta)\ **Post date:** [July 17, 2021, 6:24pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/3 "2021-07-17T18:24:55Z")
> [@jme52](#): > > As far as I can see, [https://fortran-lang.org/packages/programming](https://fortran-lang.org/packages/programming) only lists one documentation tool, FORD ([https://github.com/Fortran-FOSS-Programmers/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. It seems that FORD is back to life now and its maintenance has resumed! 🎉 ---
**Author:** ![everythingfunctional](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/everythingfunctional/32/176_2.png) [@everythingfunctional](https://fortran-lang.discourse.group/u/everythingfunctional)\ **Post date:** [July 18, 2021, 12:29am UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/4 "2021-07-18T00:29:01Z")
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. ---
**Author:** ![pcosta](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/pcosta/32/5504_2.png) [@pcosta](https://fortran-lang.discourse.group/u/pcosta)\ **Post date:** [July 18, 2021, 8:40am UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/5 "2021-07-18T08:40:12Z")
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](https://github.com/Fortran-FOSS-Programmers/ford/issues/317). So I’m optimistic and perhaps it would be nice that this would motivate new people to join the endeavor. ---
**Author:** ![msz59](https://avatars.discourse-cdn.com/v4/letter/m/3d9bf3/32.png) [@msz59](https://fortran-lang.discourse.group/u/msz59)\ **Post date:** [July 18, 2021, 8:52am UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/6 "2021-07-18T08:52:23Z")
> [@shahmoradi](#): > > Here is an example: [https://www.cdslab.org/paramonte/notes/api/kernel/index.html](https://www.cdslab.org/paramonte/notes/api/kernel/index.html) > > The preparation of this entire documentation using Doxygen took 2-3 days to complete. It hits 404 error ☹ ---
**Author:** ![shahmoradi](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/shahmoradi/32/3151_2.png) [@shahmoradi](https://fortran-lang.discourse.group/u/shahmoradi)\ **Post date:** [July 18, 2021, 4:27pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/7 "2021-07-18T16:27:39Z")
Here is a direct link: [ParaMonte: ParaMonte: Plain Powerful \Para\llel \Monte\ Carlo Library](https://cdslaborg.github.io/paramonte-kernel-doc/html/) Thanks for the ping. ---
**Author:** ![everythingfunctional](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/everythingfunctional/32/176_2.png) [@everythingfunctional](https://fortran-lang.discourse.group/u/everythingfunctional)\ **Post date:** [July 19, 2021, 12:47am UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/8 "2021-07-19T00:47:14Z")
I didn’t realize. That’s great news. ---
**Author:** ![urbanjost](https://avatars.discourse-cdn.com/v4/letter/u/0ea827/32.png) [@urbanjost](https://fortran-lang.discourse.group/u/urbanjost)\ **Post date:** [July 19, 2021, 6:11pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/9 "2021-07-19T18:11:45Z")
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. ---
**Author:** ![certik](https://yyz2.discourse-cdn.com/free1/user_avatar/fortran-lang.discourse.group/certik/32/4_2.png) [@certik](https://fortran-lang.discourse.group/u/certik)\ **Post date:** [July 19, 2021, 7:10pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/10 "2021-07-19T19:10:46Z")
> [@urbanjost](#): > > 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. That is certainly my goal. ---
**Author:** ![urbanjost](https://avatars.discourse-cdn.com/v4/letter/u/0ea827/32.png) [@urbanjost](https://fortran-lang.discourse.group/u/urbanjost)\ **Post date:** [July 19, 2021, 10:10pm UTC](https://fortran-lang.discourse.group/t/documentation-tools-for-fortran-codes/428/11 "2021-07-19T22:10:20Z")
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!