Automatic Documentation via FORD and Readthedocs

1

Moin all,

at my institute, we are developing a “Best Scientific Research Software Engineering” handbook to enable our researchers to get better at all the stuff they “forgot to teach you at grad school”. Git, testing, docs, you name it.

At the end of the day, I’d like to provide a template repository combining the following:

  • Testing via some CI (ideally GitLab and GitHub)
  • Documentation via FORD and hooks to readthedocs
  • Bonus Feature: …auto publication to the fpm registry :smiley:

Would anyone be interested in this, and would be interested in collaborating?

All the best
Paul

10 Likes
2

Seems really useful and important! At my Institute I was thinking of doing the same but in a less formal way, just a couple of talks at some point.

For an example of CI you could check: GitHub - everythingfunctional/ci_example: A simple, contrived project for demonstrating use of the GitHub CI features for a Fortran project.
I think there were some related videos too

3

I contracted with the good folks at Sourcery Institute (@everythingfunctional @rouson) who built this capability for one of my repos. The documentation uses a mix of FORD and a static Jekyll site and posts to Github pages (rather than ReadTheDocs). It works like a champ and might be a good place to start.

3 Likes
4

Started something with a similar theme, but have not worked on it a while; but basically a template for an fpm repo using git with example CD/CI scripts that assume “fpm test” will
run the unit tests:

GitHub - urbanjost/easy: steps to setup a github repository with fpm, and github actions including ford(1) documentation and unit tests

The projects listed above should add the topic “fortran-package-manager” as should every project with an fpm.toml file that wants to be visible IMO. It makes it very easy to find fpm packages. The repository will supplant it at some point, but for github-based projects just click on the topic and you enter the ring of fpm projects. And I love the eye candy the logos provide :slight_smile:

fortran-package-manager · GitHub Topics · GitHub

5

I especially like the auto-publication to the fpm repository because that’s the one of the three bullets that I haven’t managed to get around to handling myself for my projects.