Read the Docs builds failing

[mslw]

The Read the Docs build history is a long list of failures.

100 introduced readthedocs.yaml to bump Python version used on RtD and then it worked. Apparently something changed and now if we use readthedocs.yaml we also need to specify explicitly that we need to install this extension (needed by our build process) to build the docs - discovered in https://github.com/datalad/datalad-redcap/pull/17

[mslw]

Still not solved, unfortunately - but with a different error now:

https://readthedocs.org/projects/datalad-neuroimaging/builds/19483011/

[mslw]

• Read the Docs projects created before Oct 20, 2020 use Sphinx 1.8.x. New projects use the latest version. https://docs.readthedocs.io/en/stable/build-default-versions.html

• With our current setup, RtD installis default dependencies, followed by datalad-neuroimaging https://docs.readthedocs.io/en/stable/builds.html#understanding-what-s-going-on

• RtD encourages pinning dependencies https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#pinning-dependencies

This is the RtD dependency installation for this project:

python -m pip install --upgrade --no-cache-dir 
    pillow mock==1.0.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.9.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<2.3 jinja2<3.1.0

versus the same step for a fork created today:

python -m pip install --upgrade --no-cache-dir \
    pillow mock==1.0.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.9.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme readthedocs-sphinx-ext<2.3

I'm sure 1.8 might be made to work, but there's a potential mess of transitive dependencies lurking when capping sphinx alone.

Option 1: introduce docs requirements file

We could use what seems to be recommended by RtD, and tightly pin dependencies - this should work based on pip freeze from a fresh installation in a virtualenv (as of today):

# docs/requirements.txt
sphinx == 6.1.3
sphinx-rtd-theme == 1.2.0

# .readthedocs.yaml
python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .

Option 2: use existing .[devel-docs]

Or we could use the [devel-docs] requirements already present in our setup.cfg - they are much more loosely pinned, but the way they are now would essentially be equivalent to latest version. The following would lead to pip install .[devel-docs]

# .readthedocs.yaml
python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - devel-docs

Option 3: both

Or we could do everything and the kitchen sink, though that would probably mean re-installing in practice:

# .readthedocs.yaml
python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .
      extra_requirements:
        - devel-docs

[mslw]

Note: Option 2 would probably still install the default dependencies (sphinx < 2) but follow that with pip install --upgrade --upgrade-strategy eager --no-cache-dir .[devel-docs]