Ks/docs clean

[stuitje]

Description

This PR builds documentation for aragog according to the Diataxis approach. Closes FormingWorlds/PROTEUS#544.

It uses some original Sphinx documentation in ExPlanetology/aragog (converted to Markdown), but the vast majority is new. The documentation itself is divided into:

Documentation files

• homepage (index.md)
• Getting started (getting_started.md), shortly explains tutorials/howtos/explanations/reference and points to installation/firstrun tutorial
• How-to's: includes an installation how-to (installation.md) and an how-to on using NetCDF output files (netcdf.md)
• Tutorials: includes First Run tutorial (firstrun.md)
• Explanation: includes a thorough model overview (model.md)
• Reference: includes a list of publications (publications.md) and a full api reference making use of mkdocstrings (api.md)
• Code of conduct: copied from proteus (CODE_OF_CONDUCT.md)

Other files

• mkdocs.yml: the mkdocs configuration file
• .github/workflows/docs.yaml: builds the documentation via github pages
• docs/stylesheets/extra.css: necessary to render docstrings correctly in the api overview
• assets/ includes PROTEUS logos
• overrides/: a directory with a few files to force the favicon (in the browser search bar) to switch color depending on dark/light mode in chrome, safari, and firefox

source code

Finally, some changes were made to the docstrings mesh.py and solver.py to change math mode from Sphinx style (:math:) to markdown ($$).

Validation of changes

The documentation has been built locally using mkdocs serve on safari and chrome. The tutorial and how-tos have been tested as well (MacOS, Python 3.13)

Checklist

• I have followed the contributing guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my code
• My changes generate no new warnings or errors
• I have checked that the tests still pass on my computer
• I have updated the docs, as appropriate
• I have added tests for these changes, as appropriate
• I have checked that all dependencies have been updated, as required

Relevant people

@planetmariana, it would be nice, if you have time, if you could build the documentation using mdocs serve (you might have to install some dependencies; use pip install -e ".[docs]"). Then you can check whether you agree with the content of the documentation. Additional suggestions for how-to's (e.g. troubleshooting) or tutorials (or something else) are welcome.

I also added @maraattia, @timlichtenberg and @nichollsh to take a quick look if there is time.

[stuitje]

@nichollsh I implemented your suggestions and made a few more changes. What do you think?

[nichollsh]

Looks good! I agree that writing the name as Aragog is better than as 'aragog'. The former comes across as incomplete.

[nichollsh]

Please feel free to merge, @stuitje

[timlichtenberg]

looks very good, a few final suggestions, then let's merge tomorrow :>

[timlichtenberg]

Rapid! Happy to re-review in a couple of minutes.

[stuitje]

Rapid! Happy to re-review in a couple of minutes.

I should have covered everything now.

[timlichtenberg]

Go!