update the docs environment

[keewis]

Most notably:

• bump python to 3.10
• bump sphinx to at least 5.0
• remove the pydata-sphinx-theme pin: sphinx-book-theme pins to a exact minor version so pinning as well does not change anything
• xref ✨ Release candidate ✨ v1.0.0 executablebooks/sphinx-book-theme#686

Edit: it seems this is blocked by sphinx-book-theme pinning sphinx to >=3,<5. They already changed the pin, we're just waiting on a release

[dcherian]

We still have an error but sphinx is up to 5.3.0

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/xray/conda/7442/lib/python3.10/site-packages/sphinx/cmd/build.py", line 281, in build_main
    app.build(args.force_all, args.filenames)

...

  File "/home/docs/checkouts/readthedocs.org/user_builds/xray/conda/7442/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 568, in write
    self._write_parallel(sorted(docnames),
  File "/home/docs/checkouts/readthedocs.org/user_builds/xray/conda/7442/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 615, in _write_parallel
    tasks.add_task(write_process, arg, on_chunk_done)
  File "/home/docs/checkouts/readthedocs.org/user_builds/xray/conda/7442/lib/python3.10/site-packages/sphinx/util/parallel.py", line 100, in add_task
    self._join_one()
  File "/home/docs/checkouts/readthedocs.org/user_builds/xray/conda/7442/lib/python3.10/site-packages/sphinx/util/parallel.py", line 126, in _join_one
    raise SphinxParallelError(*result)
sphinx.errors.SphinxParallelError: AttributeError: can't set attribute '_table_row_index'

Sphinx parallel build error:
AttributeError: can't set attribute '_table_row_index'

[keewis]

I think we should pin sphinx-book-theme to some appropriate version, right now we have 0.0.41, which is about two years old (and is probably the last version that does not contain the upper bound on sphinx)

[keewis]

as expected that environment is not solvable because sphinx-book-theme didn't have a release since the bump of the sphinx version

[Illviljan]

Seems we're experiencing this issue now:
pydata/pydata-sphinx-theme#1220

[keewis]

with the release of sphinx-book-theme=1.0.0 yesterday we can finally move this forward.

In the process I fixed a few other docs issues so I'll merge this now to avoid having the docs CI fail on main.