Call for contribution: Fortran Sphinx extension module

Announcements
1

Hello everyone,

I’m working on a Fortran Sphinx extension module to manage auto-documentation for Fortran codes that can profit from all the features of sphinx.

I’m looking for collaborators to help me get this into a nice looking shape for the community.

If you are interested in helping out, feel fluent in both python and Fortran or are motivated to get there and like the feels of a nice looking documentation, drop me a DM here in discourse and I’ll add you to the github repo which is currently private as it is in a embryo state.

Cheers,

5 Likes
2

Wasn’t it in the interest of FORD becoming an extension of sphinx? There is also (not sure if barely on life support Documentation of fortran extensions to Sphinx — SphinxFortran 1.0 documentation). Maybe joining efforts instead of writing another one?

3

I saw that comment, haven’t seen any news in that direction…

Yep, no activity since 2015, every time I tried to use it I had errors, and their license seems restrictive… so, yes, had no choice but to start from scratch :man_shrugging:

4

Hi @hkvzjal ,
Please count me in. I am dealing with a large modern Fortran code base on windows for which I need a code documentation very badly. Tried with Doxygen, but not so effective.
Building something like this will help me too.

Thanks,
Abhi

1 Like
5

For what it’s worth, there is also the possibility to use doxygen together with exhale to generate some sphinx documentation. You can find a nice tutorial from Rohit Goswami for SymEngine (Documenting C++ with Doxygen and Sphinx - Exhale :: Rohit Goswami — Reflections).

I was pretty much in the same situation as you are when documenting benchmark.f. I found doxygen not so easy to setup and ford was too limited in terms of customization for my taste. So I also considered writing my own tool. At the end of the day I stepped back and spend way to much time fine tuning doxygen, but here are the results of my initial investigations.

Rather than using sphinx, I considered docfx, that is mostly used in the .NET environment. They recently opened to non .NET languages as long as you can output a compliant yaml file describing the API. My first idea was to use lfortran parser, generate the asr and save it to json. The json would have then been converted to yaml and Voilà!. Problem was that despite the great progresses of lfortran it could not parse my entire code and I parked the idea for later.
But this might still be an idea for @certik and his team.

6

I read that and another similar post a while back, doxygen has never been my cup of tea. Since learning Sphinx a few years back I decided to don’t turn my head back on it.

When the frustration won me over and started to work on this I also thought about using Lfortran as a base for the parser. Hopefully that will come to happen eventually, I think that it would be the sustainable approach in the future. In the meantime, (because I need a solution in the short term) I’m basing the project on this fparser2 — fparser 0.1.5.dev75+g84a4b1d documentation which I discovered recently and provides a nice parser that can be used in python without much hurdle.

Let’s see how this rolls out :wink: I’ll be keeping the community posted as we progress.

7

@davidpfister if your code is open source, just point me to it and we can fix it (or if it is not but you are willing to share with me privately, that will work too). Parsing to AST should work, or would be very easy to fix. It’s been beta quality for years, so it is expected to work. Doing semantics AST->ASR for most codes is almost there too, but it’s still alpha, so still expected to break, but usually not difficult to get working. So if you are interested, just ping me.

8

@certik, thanks!
It is open source: benchmark.f. And we already discussed one of the issue in another thread. I am using ‘compiler_version’ and ‘compiler_options’ from ‘iso_fortran_env’. Last time I checked, lfortran was not supporting these functions.

But I am following closely your progress and will give it another shot whenever possible :wink:

For the record, the issue was in the ASR (since I need all the variable names, etc…), AST works fine.

1 Like
9

BTW, as a side note, you might be interested in the benchmarking example with equation parsers. SymEngine performs very well! :+1:

1 Like
10

Thanks @davidpfister. I opened an issue for benchmarks.f: Compile benchmark.f · Issue #5297 · lfortran/lfortran · GitHub, it discovered some bugs in our parser, which is great, we’ll fix that soon. Regarding semantics (AST->ASR) we’ll fix that too, it found an interesting recursive case that we need to figure out how to handle: Compile benchmark.f · Issue #5297 · lfortran/lfortran · GitHub.

(I had a long text here that I moved into the issue above so that we don’t hijack this thread.)

11

Glad it can help :grin:.
Let’s not hijack the OP thread, we can continue this discussion in the issue you just opened.

1 Like
12

I’m the maintainer of ford, and I’m very interested in porting ford to use sphinx under the hood and basically turning it into a sphinx plugin – unfortunately, I’m spread quite thin at the moment! Ford already handles most Fortran projects out of the box, and has a pretty big userbase, so porting it to Sphinx would help a lot of people. I also need to finish off converting it to use the tree-sitter grammar, which is very fast – about 50-100x faster than fparser2.

@hkvzjal If you’re interested in building on ford, please get in touch

3 Likes