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

Author: jacobtomlinson

.readthedocs.yaml

@@ -14,7 +14,7 @@ formats: all
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.12"
 
 python:
   install:

docs/requirements-docs.txt

@@ -2,15 +2,5 @@ numpydoc
 sphinx
 sphinx-reredirects
 sphinxcontrib-mermaid
-dask-sphinx-theme>=3.0.0
+dask-sphinx-theme>=4.0.0
 sphinx-helm>=0.2.1
-
-# FIXME: This workaround is required until we have sphinx>=5, as enabled by
-#        dask-sphinx-theme no longer pinning sphinx-book-theme==0.2.0. This is
-#        tracked in https://github.com/dask/dask-sphinx-theme/issues/68.
-#
-sphinxcontrib-applehelp<1.0.5
-sphinxcontrib-devhelp<1.0.6
-sphinxcontrib-htmlhelp<2.0.5
-sphinxcontrib-serializinghtml<1.1.10
-sphinxcontrib-qthelp<1.0.7

docs/source/conf.py

@@ -79,7 +79,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"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -112,7 +112,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/source/index.rst

@@ -58,11 +58,11 @@ What is the operator?
 The Dask Operator is a set of custom resources and a controller that runs on your Kubernetes cluster and allows you to create and manage your Dask clusters as Kubernetes resources.
 Creating clusters can either be done via the :doc:`Kubernetes API with kubectl <operator_resources>` or the :doc:`Python API with KubeCluster <operator_kubecluster>`.
 
-To :doc:`install the operator <operator_installation>` you need to apply some custom resource definitions that allow us to describe Dask resources and the operator itself which is a small Python application that
+To :doc:`install the operator <installing>` you need to apply some custom resource definitions that allow us to describe Dask resources and the operator itself which is a small Python application that
 watches the Kubernetes API for events related to our custom resources and creates other resources such as ``Pods`` and ``Services`` accordingly.
 
 What resources does the operator manage?
----------------------------------------
+----------------------------------------
 
 The operator manages a hierarchy of resources, some custom resources to represent Dask primitives like clusters and worker groups, and native Kubernetes resources such as pods and services to run the cluster processes and facilitate communication.
 

docs/source/kubecluster_migrating.rst

@@ -7,7 +7,7 @@ The classic ``KubeCluster`` class has been replaced with a new version that is b
 Installing the operator
 -----------------------
 
-To use the new implementation of ``KubeCluster`` you need to :doc:`install the Dask operator custom resources and controller <operator_installation>`.
+To use the new implementation of ``KubeCluster`` you need to :doc:`install the Dask operator custom resources and controller <installing>`.
 
 The custom resources allow us to describe our Dask cluster components as native Kubernetes resources rather than directly creating ``Pod`` and ``Service`` resources like the classic implementation does.
 

docs/source/operator_extending.rst

@@ -93,11 +93,8 @@ Then you need to ensure that your ``pyproject.toml`` registers the plugin as a `
 
 .. code-block:: toml
 
-   ...
-
-   [option.entry_points]
-   dask_operator_plugin =
-      my_controller_plugin = my_controller_plugin.plugin
+   [option.entry-points.dask_operator_plugin]
+   my_controller_plugin = "my_controller_plugin.plugin"
 
 Then you can package this up and push it to your preferred Python package repository.
 
@@ -115,7 +112,7 @@ The controller uses the ``ghcr.io/dask/dask-kubernetes-operator:latest`` contain
 
    RUN pip install my-controller-plugin
 
-Then when you :doc:`install the controller deployment <operator_installation>` either via the manifest or with helm you would specify your custom container image instead.
+Then when you :doc:`install the controller deployment <installing>` either via the manifest or with helm you would specify your custom container image instead.
 
 .. code-block:: bash