FDOC: a Fortran documenter, written in Fortran

AI
1

Continuing the logical progression from A Fortran formatter written in Fortran, i present fdoc, a drop-in replacement for FORD, written completely in Fortran.

Here are the dependencies (all compiled via FPM):

fdoc-dependencies
fdoc-dependencies1146×674 51.3 KB

Fdoc depends on fformat to do the actual Fortran parsing/tokenization. Fdot is another new library, a port of just the parts of Graphviz that we need, so we don’t have the overhead of calling an external dependency for the graphs either. Fdoc also understands fypp, so we don’t need Python to do the preprocessing either (note: I’ve only ported the parts used by stdlib, so there is room for improvement there probably). Finally, OpenMP-based parallelization is used to speed up the entire process (parsing files, preprocessing, generating graphs, etc.)

Example output can be seen here.

The speed comparison is staggering. This table shows the time to generate each project’s documentation, using the project’s own settings (i.e., from the the ford.md file):

Project Lines FORD fdoc Speedup
fformat 6,902 27.1 s 0.1 s 226×
bspline-fortran 13,222 22.8 s 0.1 s 163×
rklib 17,025 62.3 s 0.2 s 271×
json-fortran 17,715 64.5 s 0.6 s 115×
Fortran-Astrodynamics-Toolkit 25,174 60.3 s 0.2 s 274×
qt-fortran 25,831 314 s 0.9 s 338×
stdlib 614,270 680 s 2.3 s 297×

So no Python needed at all, orders of magnitude faster!

4 Likes
Sphinx Fortran Domain - a sphinx extension for documenting Fortran projects
2

I tried fformat a few days ago, and it works amazingly good (and fast). It meets all my requirements and integrates well with fpm. I am definitely going to try fdoc as well. Many thanks!

Given your progress, do you think current AI is mature enough to write a standards-compliant Fortran parser in modern Fortran? Both fformat and fdoc could benefit from such a parser. In the era of AI, these tools would do more than just make source code look better. They could provide cleaner training data and tools for AI coding agents to analyze source code directly. ChatGPT seems quite optimistic about this, but I would also like to hear some human perspectives.

1 Like
3

The default theme seems much better than FORD!