Build Quokka documentation with Markdown generated HTML files

[chongchonghe]

Describe the proposal I don't find it beneficial to generate Quokka documentation using Sphinx. Usually, Sphinx is used when you have lots of docstrings/comments in your code and you generate a page from that. However, unless I'm missing something, the quokka documentation page doesn't have such content at all. Pretty much everything is hand-written in a way that is much easier to write with Markdown, and I personally believe Markdown is a better way to write stuff. So, why not use Markdown? One of the ways to do this is to use GitHub Pages, which is a service that turns Markdown files into a website and hosts them on github. I guess a wiki page inside the Quokka repo is similar, although I've never tried it.

[BenWibking]

Almost every open source project these days uses Sphinx, including AMReX and all other open-source AMReX codes. There is a large amount of material on how to use it available online, from tutorials to working around bugs. It can compile the documentation from source to HTML (or PDF) both online as a GitHub action and offline on a user's computer, and can automatically generate an index, bibliography, and has a built-in search function. So there would need to be an exceptionally compelling justification not to use it.

Sphinx requires that documentation is written in ReStructured Text (RST), instead of Markdown. However, a preference for Markdown over RST is not an exceptionally compelling reason to use something else, especially something that does not have any of the other features mentioned above.

However, it is trivial to use pandoc to convert RST to Markdown:

pandoc --from=markdown --to=rst --output=index.rst index.md

So you can write Markdown with the existing system.