Keeping the docs current

[effigies]

We're currently manually pushing the docs to https://bids-standard.github.io/pybids/, which is easy to forget, and the docs are currently out-of-date (0.9). It would be good to make an explicit process to update them or set up something automatic like ReadTheDocs.

ReadTheDocs also has the advantage of keeping old versions around, which might be useful for reference as the API changes.

[tyarkoni]

Should be easy enough; to push the docs I just checkout the gh-pages branch and run install_docs.sh. So I think if you just add that to CI, we should be good.

[effigies]

I assume only on tag builds?

[effigies]

@tyarkoni Just FYI the docs don't build with modern Sphinx. We should add a doc extra (and/or doc-requirements.txt) with the required versions so that script can create a venv and build.

[tyarkoni]

Will take a look... might be better to fix whatever's failing so we're not stuck with old sphinx versions.

[sappelhoff]

might be better to fix whatever's failing so we're not stuck with old sphinx versions

I think the m2r package is the main culprit (see: scikit-hep/pyhf#818). It breaks when it's being used as a sphinx extension (like in our case).

A fix could be to call m2r in the docs build process, rather than using it as a sphinx extension. Should be simple enough because as it seems to me, only CHANGELOG.md needs to be converted.