Move documentation to markdown and mkdocs
brynpickering opened this issue · comments
Problem description
We rely on Sphinx and ReStructuredText (.rst) at the moment, which is fine but we would do better to move to markdown, for the following reasons:
- It is not as easy to write as markdown. E.g., there is very little clarity over how headings/subheadings should be defined relative to each other (these headings also confuse the git merge helper in VSCode as they look like the merge conflict lines).
- We use a custom flavour of the old flask theme for our docs theme. These files are our oldest, untouched ones (10 years old!) in the repo. At some point this is going to fail entirely, so we would do better to rely on a maintained (and possibly sleeker) theme, like material for mkdocs.
- mkdocs has arguably a broader plugin/extension library available, including mkdocs-jupyter which would allow us to render jupyter notebooks as pages in our docs.
Calliope version
v0.7.0.dev
For an example mkdocs config file, see: https://github.com/arup-group/pam/blob/main/mkdocs.yml
For example hooks and custom CSS, see: https://github.com/arup-group/pam/tree/main/docs/static
Done as of merging #538