Leverage uv for documentation in nox session

CONTRIBUTING.md

@@ -111,7 +111,7 @@ you'll want to run the test suite locally.
 
 The easiest way to run the test suite is to use
 [**Nox**](https://nox.thea.codes/en/stable/). You can install Nox
-with pip: `pip install -U nox`. Nox provides several advantages, but the
+with pip: `pip install -U "nox[uv]"`. Nox provides several advantages, but the
 biggest one is that it builds an isolated virtualenv for running tests. This
 means it does not pollute your system python when running. However, by default
 Nox will recompile rustworkx from source every time it is run even if there
@@ -302,13 +302,21 @@ update the code formatting to conform to the style.
 
 Just like with tests building documentation is done via Nox. This will handle
 compiling rustworkx, installing the python dependencies, and then building the
-documentation in an isolated venv. You can run just the docs build with:
+documentation in an isolated venv. 
+
+Our documentation setup requires that the [uv](https://github.com/astral-sh/uv)
+backend for Nox is installed. That can be done with `pip install -U "nox[uv]"`.
+
+You can run just the docs build with:
 ```
 nox -e docs
 ```
 which will output the html rendered documentation in `docs/build/html` which
 you can view locally in a web browser.
 
+> [!TIP]
+> If you run `nox -e docs -- -j auto`, the documentation uses all CPUs and builds faster.
+
 #### rustworkx-core documentation
 
 To build the rustworkx-core documentation you will use rust-doc. You can do this
@@ -327,6 +335,16 @@ web browser by running:
 cargo doc -p rustworkx-core --open
 ```
 
+#### Updating documentation dependencies
+
+The documentation workflow is currently our step with the most dependencies. Even
+though `rustworkx` currently has very few Python dependencies, our documentation depends
+on `sphinx` and many others. Therefore, `uv.lock` file contains a frozen list of what
+can be used for the workflow.
+
+If you need to add or remove dependencies, update `pyproject.toml` (specifically the `docs`
+section in `dependency-groups`), and then run `uv sync --all-groups` to update `uv.lock`.
+
 ### Type Annotations
 
 If you have added new methods, functions, or classes, and/or changed any

noxfile.py

@@ -8,7 +8,6 @@
 deps = nox.project.dependency_groups(pyproject, "test")
 lint_deps = nox.project.dependency_groups(pyproject, "lint")
 stubs_deps = nox.project.dependency_groups(pyproject, "stubs")
-docs_deps = nox.project.dependency_groups(pyproject, "docs")
 
 def install_rustworkx(session):
     session.install(*deps)
@@ -39,16 +38,35 @@ def lint(session):
     session.run("cargo", "fmt", "--all", "--", "--check", external=True)
     session.run("python", "tools/find_stray_release_notes.py")
 
-@nox.session(python=["3"])
+# For uv environments, we keep the virtualenvs separate to avoid conflicts
+@nox.session(python=["3"], venv_backend="uv", reuse_venv=False, default=False)
 def docs(session):
-    install_rustworkx(session)
-    session.install(*docs_deps, "-c", "constraints.txt")
-    session.run("python", "-m", "ipykernel", "install", "--user")
-    session.run("jupyter", "kernelspec", "list")
+    session.env["UV_PROJECT_ENVIRONMENT"] = session.virtualenv.location
+    session.env["UV_FROZEN"] = "1"
+    # faster build as generating docs already takes some time and we discard the env
+    session.env["SETUPTOOLS_RUST_CARGO_PROFILE"] = "dev"
+    session.run("uv", "sync", "--only-group", "docs")
+    session.install(".")
+    session.run(
+        "uv", "run", "--", "python", "-m", "ipykernel", "install", "--user"
+    )
+    session.run("uv", "run", "jupyter", "kernelspec", "list")
     session.chdir("docs")
-    session.run("sphinx-build", "-W", "-d", "build/.doctrees", "-b", "html", "source", "build/html", *session.posargs)
+    session.run(
+        "uv",
+        "run",
+        "sphinx-build",
+        "-W",
+        "-d",
+        "build/.doctrees",
+        "-b",
+        "html",
+        "source",
+        "build/html",
+        *session.posargs,
+    )
 
-@nox.session(python=["3"])
+@nox.session(python=["3"], default=False)
 def docs_clean(session):
     session.chdir("docs")
     session.run("rm", "-rf", "build", "source/apiref", external=True)

pyproject.toml

@@ -69,6 +69,7 @@ build-backend = "setuptools.build_meta"
 [dependency-groups]
 testinfra = [
     "nox==2025.5.1",
+    "uv==0.7.8",
 ]
 test = [
   "setuptools-rust",
@@ -94,11 +95,12 @@ docs = [
     "pydot",
     "pillow>=4.2.1",
     "reno>=3.4.0",
-    "qiskit-sphinx-theme~=1.14.0rc1",
+    "qiskit-sphinx-theme==1.16.1",
     "matplotlib>=3.4",
     "sphinx-reredirects",
     "sphinxemoji",
     "ipykernel",
+    "lxml_html_clean",
 ]
 releaseinfra = [
     "cibuildwheel==2.23.2",