Version our docs

[hammer]

It will add complexity to our doc build and push but I think we're at the point now where we should support searching different versions of the docs, including the latest version of main.

[hammer]

If we want to stay on GitHub Pages, there seem to be a few options:

• https://github.com/sphinx-contrib/sphinxcontrib-versioning (abandoned)
• https://github.com/Holzhaus/sphinx-multiversion
• https://github.com/buildthedocs/btd

Otherwise it may be time to look into RTD again, cf. https://docs.readthedocs.io/en/stable/versions.html

[jeromekelleher]

We're doing a homegrown docs versioning for tskit and related projects, which just gives (I think) the release and tip of main versions. Code is here.

It's not as good as RTD's setup, but it does most of things you want.

Note there's some ugly string replacement in the Makefile to get the actual version numbers into the built docs.

[tomwhite]

We already have some of this, but it would be good to improve it and make it more standard. In particular, we don't link to the different versions we have available.

• Versioned docs are at https://pystatgen.github.io/sgkit//, e.g. https://pystatgen.github.io/sgkit/0.3.0/
  • Built manually by following https://github.com/pystatgen/sgkit/issues/608#issuecomment-891117795
• The latest version of main is at https://pystatgen.github.io/sgkit/latest/
  • Built automatically by https://github.com/pystatgen/sgkit/blob/main/.github/workflows/docs.yml

[hammer]

@tomwhite ah yes I do recall that now!

I think there are at least 3 tasks here moving forward:

• Make the most recent release the default docs
• Allow navigating to other doc versions
• Update the search typeahead to only search the current version of the docs

[hammer]

It looks like a version switcher is coming to the PyData Sphinx theme, from which our theme inherits: pydata/pydata-sphinx-theme#23.

[tomwhite]

Docs on how to add a version switcher: https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/version-dropdown.html