Fortran-lang webpage: Sphinx Edition?

Announcements
1

This topic branches from our internationalization effort in Promoting Fortran in non-English languages.

After looking into enabling internationalization of the Fortran-lang webpage, we arrived at the conclusion that our current static side generator (jekyll) is simply not up for the job of hosting translated and localized content. Currently, I’m exploring sphinx as alternative static side generator, which many of you probably now from being Python’s main documentation tool.

So far the result looks quite okay, you can check it out here. It’s not complete yet and there is a lot of work left to be done. The source of this is hosted on my fork of the Fortran-lang webpage for now:

I’m looking for help on this effort, if you have experience with sphinx, sphinx-theming, restructuredtext, myst-markdown, bootstrap CSS, … basically everything. Any help is appreciated here. I’ve also opened an issue tracker and a discussion board at my fork, feel free to drop me feedback there as well.

Links to the tools I’m currently using for this:

5 Likes
2

Currently, this is only for the main Fortran-lang website right?

It would be nice if the main page and library/tool pages play well together. The Sphinx-Fortran plugin was one step in this direction, but it looks uncomplete. @certik has suggested piggy-backing on Sphinx previously. The MOM6 project (@marshallward) also uses Sphinx for it’s documentation. While okay-looking in general, I am not too fond of the procedure information layout (e.g. mom_file_parser module reference — MOM6 0.2a3 documentation).

1 Like
3

Thank you @awvwgk for working on this. The demo looks promising. Two questions:

  1. I see support for Markdown through myst-parser, but I see rst files in the repo. Will it be as easy as before to write everything in Markdown? I find it easier to read and write and I think it’s more ubiquitous.
  2. Does sphinx-panels support arbitrary CSS to style any part of the website? I can’t tell from the webpage if that is true.

I think that if this checks off the internationalization, Markdown, and CSS boxes, it’s a good solution to transition to.

1 Like
4

The posts are done in markdown right now, the minibooks will preferably stay in markdown as well. I used rst because the sphinx-panels syntax I’m using to build the bootstrap grids looks much more readable in rst than in md (for rst you can check the indentation, for md you have to count the backticks in the code fence). I’ll do the missing parts of the webpage next weekend (hopefully).

I would say that everything that is currently raw HTML will probably end up as rst, while everything that is markdown will stay markdown.

I think it does (.. div:: should do the trick), but mostly this would be in the responsibility of the theme rather than the markup (we will probably have to create our own sphinx theme in the long run).

3 Likes
5

Thank you @awvwgk for working on this! It looks very promising. I agree with the direction.