Enable versioned doc support

[leofang]

[bryevdv]

Using PSD theme (or any derived themes e.g. the NV theme) this is nominally a matter of adding a switcher.json and updating it on new releases:

https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html

Is the long-term plan to stick with GH-pages, or move to something else? For the current GH pages, the docs dir will need to be re-organized keeping each version in a subdirectory.

[leofang]

Thanks for checking, @bryevdv!

Using PSD theme (or any derived themes e.g. the NV theme) this is nominally a matter of adding a switcher.json and updating it on new releases:

It seems we currently use the furo theme (first time hearing this theme...) https://github.com/NVIDIA/cuda-python/blob/e1e332564c48db556212d59262a149b1a63285e8/docs_src/source/conf.py#L57-L58 @vzhurba01 do you recall why we used furo instead of the PyData one?

Note that furo still does not have multi-ver doc support (pradyunsg/furo#372; WIP in https://github.com/pradyunsg/furo/pull/500), so we have 2 choices:

1. Switch to PyData or NV theme
2. Hack the existing theme to add a simple, json-based multi-ver support (which I showed can be done, see, e.g. nvmath-python et al). I believe the same approach can be applied to furo too, given that it already has the infra following RTD.

Is the long-term plan to stick with GH-pages, or move to something else?

I think using the GH pages is OK. The internal workflow can be slightly more demanding.

For the current GH pages, the docs dir will need to be re-organized keeping each version in a subdirectory.

That is fine with me. I'd also like to use this opportunity to purge the doc artifacts from the main/release branches, following the common practice. In short:

• The main/release branches should only contain the doc sources (= source code + Sphinx rst files)
• The gh-pages branch that we use to publish the docs should only contain the doc artifacts (=html files)
  • If we switch to a multi version doc, all versions will be kept under a subdirectory as you suggested

[leofang]

Another perhaps silly question: Does the GH page support the JS + Json based version selector?

[vzhurba01]

@vzhurba01 do you recall why we used furo instead of the PyData one?

I don't recall. Looking back I see that @mmccarty was the one who helped up setup the docs initially.

[leofang]

Bumping this to P0 as this could have been a gatekeeper for issues like #140.

[leofang]

2. Hack the existing theme to add a simple, json-based multi-ver support (which I showed can be done, see, e.g. nvmath-python et al). I believe the same approach can be applied to furo too, given that it already has the infra following RTD.

I confirm in #165 that this works, so we can defer the theme change to a later stage and not mixing it together with other decisions to make.