[WIP] Add docs prototype (Sphinx, Read the Docs)

[EZoni]

Add prototype of documentation infrastructure based on

• Sphinx (generation)
• Read the Docs (deployment)

To-do:

• Test local build
  • install dependencies from docs/requirements.txt
  • run make build in the docs/ directory
• Test online build (on individual fork and branch)

[EZoni]

Additional Sphinx-friendly deployment options (e.g., GitHub Pages) can be found at https://www.sphinx-doc.org/en/master/tutorial/deploying.html.

[DavidSagan]

So this brings up the issue of what documentation environment to use (#1). I propose discussing this on the Issue forum first.

[EZoni]

@DavidSagan

Hi, yes, a few days ago I was asked by @jlvay to open a prototype PR, precisely due to #1, in order to have a concrete example to look at and discuss during next week's meeting. The current example is based on how documentation is done in some of the BLAST codes, e.g., WarpX, which does not have to be the final choice in this case. No intention to skip over #1.

[DavidSagan]

@EZoni Understood. Thanks for your input.

[rdemaria]

I think the choice should be the most comfortable for the maintainers/editors and will be good enough for everybody else.

I found anyway interesting sharing knowledge on documentation framework options. In this context, I would to mention a new effort to replace latex as a whole, https://typst.app/, which the maintainers/editors could also consider if they feel particularly adventurous…

[DavidSagan]

@EZoni Is this compatible with MyST?