RFC: Do we want versioned docs? And do we want to maintain them ourselves?

[effigies]

I can't remember if we moved from readthedocs or just started on gh-pages, but we now have versioned docs at https://nipreps.org/smriprep using an unmaintained Sphinx plugin called sphinxcontrib-versioning. I see niworkflows was moved away to some custom code (nipreps/niworkflows#656). It's unclear to me how much advantage we derive from maintaining old versions, and even less building the code ourselves to do it when readthedocs exists.

I see four options for sMRIPrep in rough order of preference:

1. Move (back?) to ReadTheDocs and use normal Sphinx
2. Drop versioning altogether and just push a single version to gh-pages
3. Move to (and maintain) GitHub actions custom code
4. Maintain a fork of sphinxcontrib-versioning

I think 4 is a bad choice but possibly the quickest path forward in the short term (we're already pinning @rwblair's fork).

[effigies]

I did at least fix the current bug, but I do not want to maintain sphinxcontrib-versioning. It is a mess of test failures.

[mgxd]

+1 to moving to RTD, though I vaguely remember trying this (or maybe it was for niworkflows) and something not working out

cc @oesteban

[oesteban]

I like to self-archive the documentation and hence typically prefer to stay away from RTD. But I don't have very strong feelings, and concede that, it's better to have a functional documentation on RTD than broken documentation self-archived.

That all said,

• the sphinxcontrib-versioning package is useful to create the archive if you haven't been keeping all versions. I don't remember where we are with smriprep, but in any case, once the documentation is generated, you can just forget about this sphinx extension.
• dropping the versioned docs seems reasonable for sMRIPrep. Its API is pretty stable. A sub-option here is to drop all previous docs and keep some light versioning by only maintaining a head of supported minor series.