Add skeleton of mkdocs

[sjpfenninger]

First skeleton of mkdocs

Open issues:

• custom_math.py could also run through gen-files but because it is quite slow, I think it's better to run it in a seprate pre_build step. Already including those generated markdown files let's build time increase from ~1 second to around 10 seconds, so there is some issue with them anyway. The idea for now would be to run python ./pre_build/generate_math.py and any other pre-build steps manually (and in the case of readthedocs, add this as pre-build steps in the readthedocs configuration).
• The rendering of the fenced math blocks needs fixing, e.g.: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#alternative-math-blocks
• extra: version: 0.7.0 in the configuration should come from the installed calliope module, not be hardcoded in the config file
• Only three custom math files as proof-of-concept, with the rest to be moved once New model definition structure #518 is merged

The idea would be to sort out any issues with the basic setup here, merge this basic setup, then revise and move over the remaining documentation step-by-step, thus also moving from the old doc to the new docs directory.

Reviewer checklist:

• Test(s) added to cover contribution
• Documentation updated
• Changelog updated
• Coverage maintained or improved

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (e6b7263) 94.98% compared to head (7247860) 95.00%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #526      +/-   ##
==========================================
+ Coverage   94.98%   95.00%   +0.01%     
==========================================
  Files          24       24              
  Lines        3290     3301      +11     
  Branches      702      651      -51     
==========================================
+ Hits         3125     3136      +11     
  Misses         96       96              
  Partials       69       69              

Files	Coverage Δ
src/calliope/backend/latex_backend_model.py	96.24% <100.00%> (+0.24%)	⬆️
src/calliope/util/schema.py	90.32% <100.00%> (+0.49%)	⬆️

[brynpickering]

For math to be rendered, do you just need to add the relevant config and javascript?

https://squidfunk.github.io/mkdocs-material/reference/math/

[brynpickering]

most of the mkdocs stuff can be installed from conda-forge so I would move them out of pip where possible

[sjpfenninger]

👍

[brynpickering]

This doesn't seem necessary. RTD allows for version warnings: https://docs.readthedocs.io/en/stable/versions.html#version-warning

Then you don't need to track version in the mkdocs config and don't need to worry about making it dynamic.

[sjpfenninger]

True, but I think it's still nice to show the version in the built docs if that's possible without too much effort.

[brynpickering]

It would be good to follow the convention of one sentence per line so that future git diffs are simpler. Here's a proponent

[sjpfenninger]

👍

[brynpickering]

This is showing up as brand new. Have any changes been made from the other version?

[sjpfenninger]

Minor changes. I'll move the old file to the new location in a next commit so that the changes are visible.

[brynpickering]

--8<-- CHANGELOG.md if using pymdownx.snippets

[sjpfenninger]

I tried that, but the on_page_markdown hook in changelog_highlight.py doesn't work with snippets and I'm not sure why. Possibly because the snippets pre-processor runs after that. So I propose to stick to this as-is for now.

[sjpfenninger]

For math to be rendered, do you just need to add the relevant config and javascript?

https://squidfunk.github.io/mkdocs-material/reference/math/

Not enough if you want the fenced blocks to work (```math ...). The easiest solution might just be to replace those with the $$...$$ block syntax.

From https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#alternative-math-blocks I gather something like this ought to work but it doesn't so far:

  - pymdownx.arithmatex:
      generic: true
  - pymdownx.superfences:
      custom_fences:
        - name: math
          class: arithmatex
          format: !!python/name:pymdownx.arithmatex.arithmatex_fenced_format