Unblock documentation build

[milesgranger]

• Part of Doc build broken #10805
• Tests added / passed
• Passes pre-commit run --all-files

Just restricting the newish slew of releases from sphinxcontrib which made the sphinx>=5 start failing. Feel free to merge this now, while I still poke at who's causing the <=4.5.0 restriction.

---

Caused by dask-sphinx-theme pinned to sphinx-book-theme==0.2.0 which requires sphinx<5.
xref dask/dask-sphinx-theme#68

[milesgranger]

@phofl I'm not sure if we want 7c14d41, but as it's not a library, pinning everything seems like an easy way to protect against future breakages from others upgrading their dependencies.

[milesgranger]

Tried with mamba: https://readthedocs.org/projects/dask/builds/23132383/
but not happy. Can try again in a follow-up, but using pip with the pinned packages works for now at least.

environment.yml

name: dask-docs
channels:
  - conda-forge
dependencies:
  - python=3.11
  - cloudpickle>=1.5.0
  - pandas>=1.4.0
  - sphinx>=4.0.0
  - numpydoc
  - dask-sphinx-theme>=3.0.0
  - sphinx-click
  - sphinx-copybutton
  - sphinx-remove-toctrees
  - sphinx-design
  - jupyter_sphinx
  - toolz
  - fsspec
  - scipy
  - pytest
  - pytest-check-links
  - requests-cache
  - ipython
  - ipykernel<6.22.0
  - pip
  - pip:
      - sphinx-tabs
      - sphinx_autosummary_accessors
      - git+https://github.com/dask/distributed

[github-actions]

Unit Test Results

See test report for an extended history of previous test failures. This is useful for diagnosing flaky tests.

     15 files  ±0       15 suites  ±0   3h 27m 54s ⏱️ - 14m 37s
 12 941 tests ±0   11 593 ✅ +3     929 💤 ±0  419 ❌  - 3 
160 329 runs  ±0  143 023 ✅ +3  16 887 💤 ±0  419 ❌  - 3 

For more details on these failures, see this check.

Results for commit 57569d8. ± Comparison against base commit ca42dcf.

♻️ This comment has been updated with latest results.

[crusaderky]

-1 from me about pip-compile. Past experience with exact pins has been unexpectedly painful for me.
Can we just add the 5 new restrictions on sphinxcontrib to requirements-doc.txt?

[milesgranger]

-1 from me about pip-compile. Past experience with exact pins has been unexpectedly painful for me.
Can we just add the 5 new restrictions on sphinxcontrib to requirements-doc.txt?

Sure thing, no problem. Out of curiosity, do you remember what your pains have been? W/o pinning application requirements I find myself doing this little number every now and again. My experience with fully pinned requirements outside of libs have been rather pleasant.

[jrbourbeau]

Thanks @milesgranger! One minor comment about a comment

[crusaderky]

Sure thing, no problem. Out of curiosity, do you remember what your pains have been? W/o pinning application requirements I find myself doing this little number every now and again. My experience with fully pinned requirements outside of libs have been rather pleasant.

My experience, specifically with conda, is that builds can be deleted by the author or by maintenance bots and it's happened to me many times that an exact-pin conda environment (output of conda env export) will just stop working after a while because one maintainer of one of the 200, mostly obscure, packages in the environment has been rebuilt by the author for whatever reason and the previous build has been deleted.

I don't have first-hand experience with pip.