Host documentation on readthedocs.io

[hukkin]

• Create docs with either
  - MkDocs
  - Sphinx + CommonMark or MyST

• Build the docs in Github Actions.

• Publish on readthedocs.io

[chrisjsewell]

Ideally Sphinx + MyST + RTD, the same as the rest of EBP 😬

You don't actually need to run a GH action, just turn on PR runs on RTD:
https://docs.readthedocs.io/en/stable/guides/autobuild-docs-for-pull-requests.html

[hukkin]

Thanks for the input, I really don't have much experience in any of this.

Sphinx + MyST + RTD sounds great. Or if we want to keep using pre-commit try-repo ... to run mdformat against its own docs, then maybe start with Sphinx + CommonMark and move to MyST, when we can come up with the necessary plugins for mdformat to handle MyST? I kinda like the pre-commit try-repo in that it shows we trust the tool enough to format our own docs with it, and also makes mdformat docs showcase what the output looks like.

You don't actually need to run a GH action, just turn on PR runs on RTD:

Nice! Maybe it's possible to use a GH action to "validate" the docs though? Fail CI if docs fail building, so we know not to merge a PR unless the docs are fixed? Or does Sphinx build ever fail? I'm still a noob here 😄

[chrisjsewell]

Sphinx + CommonMark and move to MyST

Oh MyST is already commonmark compliant. Its just add extra (optional) syntax plugins to the parser. If you don't use them, then it works exactly the same as CommonMark (we are in fact in talks with RTD to deprectate ReCommonMark in favour of MyST)

Fail CI if docs fail building

Yep this already happens with the RTD builds (you can see the check e.g. in executablebooks/markdown-it-py#58), you just need to add to the repo https://github.com/executablebooks/markdown-it-py/blob/master/.readthedocs.yml

[chrisjsewell]

I can try to get round to making a PR for it at some point 😄

[hukkin]

Its just add extra (optional) syntax plugins to the parser.

Yeah this is what I was thinking could be problematic. But I think you are right, we don't really have to use the extra syntax and if we want to in some files, then skip mdformatting that file etc.

Yep this already happens with the RTD builds

Nice!

I can try to get round to making a PR for it at some point smile

This would be amazing!