ecTrans documentation

[samhatfield]

ecTrans currently has no documentation beyond the relevant chapter of the IFS documentation. An open-source project ought to have at least instructions for building and running the code and a documentation of the API (in this case the routines in src/trans/external.

I propose to use mkdocs to build a basic documentation site using Markdown. This will use the Readthedocs theme as that's what everyone is used to, but there are other themes available.

mkdocs allows you to build a static site with minimal overhead. Just a mkdocs.yml file and some markdown files. I like it because all of the static site plumbing can be kept out of the main ecTrans repository. For now someone could build the documentation locally and upload it to a sites.ecmwf.int, but in future we could find a way to do this automatically with a Github action.

I suggest sections of

• Introduction: overview of the spectral transform algorithm (written from a serial perspective) and decomposition strategy for ecTrans.
• Installation: how to build with CMake and description of requirements of ecTrans (i.e. MPI, BLAS, FFTW, Fiat).
• Usage: a minimal working example of how to use ecTrans.
• Benchmarking: a guide for how to build a scheduler submission script to benchmark ecTrans (targeting Slurm).
• API: a detailed description of all the external routines.

See samhatfield/docs for an idea of how this looks.

And the site itself:

Any thoughts @wdeconinck @marsdeno @ioanhadade @reuterbal?

[reuterbal]

Fully supportive of this idea!

I like the use of a readthedocs theme, which is in line with what we use elsewhere. Some of these documentations are made available directly on readthedocs.io, but we have also the option to use https://sites.ecmwf.int/docs, where for example Loki and Atlas documentation is hosted. I believe we have examples for both what the Github actions setup needs to look like to automatically update this.

Just two things I'd throw in to consider:

1. Please include a contributing section in the readme (which is embarrisingly empty right now) that mentions explicitly the requirement to sign a CLA. See for example the relevant section in the ecwam readme: https://github.com/ecmwf-ifs/ecwam?tab=readme-ov-file#contributing
2. In my experience, the API documentation is almost guaranteed to be out of sync most of the time if it isn't auto-generated from the Fortran. I think Ford and Doxygen have this ability but don't necessarily integrate flawlessly with mkdocs. But they have also other advantages such as dependency graph visualisation, which might make them worthwile investigating at least?

[samhatfield]

1. Sure, good point.
2. Yes I'm a big fan of Ford. My issue with Ford in this case is that it doesn't distinguish between the external (which is what most people will care about) and internal routines. As a result the Ford page is a bit overwhelming for a first-time user. I think the best approach is just to have both. If we could somehow parse the include files (setup_trans0.h etc.) to automatically generate Markdown docblocks that render to what you see above, that would be really cool.

[samhatfield]

Turns out Ford supports arbitrary Markdown-based static sites. So I was able to add my own User Guide section! Pretty cool. Let's go with Ford then.

[samhatfield]

Docs now live at https://sites.ecmwf.int/docs/ectrans/.

[wdeconinck]

That's super nice Sam, especially as the previous FORD documention is no longer auto-generated within ifs-source. The special API documentation is nice but would be cool if it could be autogenerated from in-code documentation of just the interface header files, which we can extend.

We may want to filter out the transi sources from this FORD documentation. It has its own doxygen (see https://github.com/ecmwf-ifs/ectrans/blob/main/src/transi/transi.h) Could you also add support to generate the doxygen for transi and add it to the domain, e.g. https://sites.ecmwf.int/docs/ectrans/transi and put a link in the FORD documentation?

[samhatfield]

We could certainly find a way to automatically extract the docblock from each of the header files and stitch them together. I'll add that to the TODO list.

And adding a separate build step for the transi Doxygen, good idea :)