Update docs theme and remove docs env pins (#9125)

Author: jacobtomlinson

docs/requirements.txt

@@ -3,15 +3,8 @@ tornado
 toolz
 cloudpickle
 git+https://github.com/dask/dask
-sphinx
-dask-sphinx-theme>=3.0.0
-# FIXME: `sphinxcontrib-*` pins are a workaround until we have sphinx>=5.
-#        See https://github.com/dask/dask-sphinx-theme/issues/68.
-sphinxcontrib-applehelp>=1.0.0,<1.0.7
-sphinxcontrib-devhelp>=1.0.0,<1.0.6
-sphinxcontrib-htmlhelp>=2.0.0,<2.0.5
-sphinxcontrib-serializinghtml>=1.1.0,<1.1.10
-sphinxcontrib-qthelp>=1.0.0,<1.0.7
+sphinx>=8.0.0
+dask-sphinx-theme>=4.0.0
 sphinx-click
 memray
 sphinx_design

docs/source/active_memory_manager.rst

@@ -28,7 +28,7 @@ causes increased overall memory usage across the cluster.
 
 Enabling the Active Memory Manager
 ----------------------------------
-The AMM is enabled by default. It can be disabled or tweaked through the :doc:`Dask
+The AMM is enabled by default. It can be disabled or tweaked through the :external+dask:doc:`Dask
 configuration file <configuration>`:
 
 .. code-block:: yaml

docs/source/api.rst

@@ -61,7 +61,7 @@ The client connects to and submits computation to a Dask cluster (such as a :cla
 
 .. autosummary::
    as_completed
-   distributed.diagnostics.progressbar.progress
+   diagnostics.progressbar.progress
    wait
    fire_and_forget
    futures_of
@@ -73,10 +73,10 @@ The client connects to and submits computation to a Dask cluster (such as a :cla
 **Utilities**
 
 .. autosummary::
-   distributed.utils.Log
-   distributed.utils.Logs
-   distributed.diagnostics.memray.memray_scheduler
-   distributed.diagnostics.memray.memray_workers
+   utils.Log
+   utils.Logs
+   diagnostics.memray.memray_scheduler
+   diagnostics.memray.memray_workers
 
 
 Asynchronous methods

docs/source/conf.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from pathlib import Path
+
 from docutils.parsers.rst import directives
 
 # -- Configuration to keep autosummary in sync with autoclass::members ----------------------------------------------
@@ -86,7 +88,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -385,8 +387,8 @@
 # Link to GitHub issues and pull requests using :pr:`1234` and :issue:`1234`
 # syntax
 extlinks = {
-    "issue": ("https://github.com/dask/distributed/issues/%s", "GH#"),
-    "pr": ("https://github.com/dask/distributed/pull/%s", "GH#"),
+    "issue": ("https://github.com/dask/distributed/issues/%s", "GH#%s"),
+    "pr": ("https://github.com/dask/distributed/pull/%s", "GH#%s"),
 }
 
 # Configuration for intersphinx: refer to the Python standard library
@@ -432,9 +434,8 @@ def copy_legacy_redirects(app, docname):
     if app.builder.name == "html":
         for html_src_path, new in redirect_files:
             page = redirect_template.format(new=new)
-            target_path = app.outdir + "/" + html_src_path
-            with open(target_path, "w") as f:
-                f.write(page)
+            target_path = Path(app.outdir) / html_src_path
+            target_path.write_text(page)
 
 
 class AutoAutoSummary(Autosummary):

docs/source/scheduling-policies.rst

@@ -268,7 +268,7 @@ Adjusting or disabling queuing
 *adjusting this parameter.*
 
 Queuing behavior is controlled by the ``distributed.scheduler.worker-saturation`` config
-value. This is set via the :doc:`Dask configuration system <configuration>`. The config
+value. This is set via the :external+dask:doc:`Dask configuration system <configuration>`. The config
 value must be set on the scheduler, before the scheduler starts.
 
 The value controls how many initial chunks of data workers will have in memory at once.

docs/source/tls.rst

@@ -52,7 +52,7 @@ One can also pass additional parameters:
 
 All those parameters can be passed in several ways:
 
-* through the Dask :doc:`configuration file <configuration>`;
+* through the Dask :external+dask:doc:`configuration file <configuration>`;
 * if using the command line, through options to ``dask scheduler`` and
   ``dask worker``;
 * if using the API, through a ``Security`` object.  For example, here is