Leverage uv for documentation in nox session (#1420)

* Modernize setup.py

* Farewell to retworkx

* Add release note about retworkx removal

* Move even more data to pyproject.toml

* PEP 639 says this is deprecated

* Add dependency groups later

* Move even from setup.py to pyproject.toml

* Migrate all setup.py to pyproject.toml

* Move nox dependencies to pyproject.toml

* Document new way to do debug builds now that we no longer use setup.py

* Better way to phrase the documentation

* Remove duplicate section

* Try updating setuptools for coverage job

* Add docs dependency group as well

* Make description the same as the paper

* This doesn't work yet

* Pin uv in CI

* Make workflow work with newer Python versions

* Pass frozen via environment variables

* Update CONTRIBUTING.md to mention uv.lock procedures

* Explicitly install rustworkx and use debug mode

* Use multiple threads in sphinx

* Don't make -j auto mandatory in CI

* Document how to build faster in the guide

* Fix typo

* Revert retworkx code

* Say this will be the last retworkx release

* Trying to make retworkx work

* retworkx has its own setup.py

* Account for new directory when publishing

* Document setuptools-rust

* Edit message saying it is the final release

* sunset -> retired

* Endline

* Frozen is implied

* Ensure setuptools-rust is up-to-date

* Use setuptools>=70.1.0 and remove wheel

* Apply suggestions from code review

Co-authored-by: Matthew Treinish <[email protected]>

* Black

* Use dependency groups in CI

* Trying a newer setup-tools

* Fix coverage

* testinfra -> releaseinfra

* Pip 25.1 arrives by default on GitHub

* Fix py-project toml

* Update uv in uv.lock

* Use uv 0.7.8

* Use uv 0.7.8 (pyproject.toml)

---------

Co-authored-by: Matthew Treinish <[email protected]>

Author: IvanIsCoding

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",