Merge #79

79: Use `uv` to build the documentation r=Hoverbear a=pietroalbini

This PR switches criticalup's documentation to pull shared resources from PyPI instead of using a submodule. It also switches managing Python to `uv`.

Co-authored-by: Pietro Albini <pietro.albini@ferrous-systems.com>
Co-authored-by: Ana Hobden <operator@hoverbear.org>

.github/workflows/ci.yml

@@ -186,21 +186,20 @@ jobs:
       - name: Checkout the source code
         uses: actions/checkout@v4
 
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
       - name: Build documentation and check links
         working-directory: ./docs
         run: ./make.py --check-links
 
-      - name: Install Python dependencies
-        working-directory: ./docs
-        run: python3 -m pip install reuse black flake8
-
       - name: Verify Python code formatting
         working-directory: ./docs
-        run: black . --check --diff --color
+        run: uvx black . --check --diff --color
 
       - name: Lint Python code with flake8
         working-directory: ./docs
-        run: flake8 . --exclude .venv
+        run: uvx flake8 . --exclude .venv
 
       - name: Upload GitHub Pages artifact
         uses: actions/upload-pages-artifact@v3

docs/README.rst

@@ -1,30 +1,25 @@
 .. SPDX-FileCopyrightText: The Ferrocene Developers
 .. SPDX-License-Identifier: MIT OR Apache-2.0
 
-================================
+========================
 CriticalUp Documentation
-================================
+========================
 
 .. raw:: html
 
    <p align="center"><a href="https://criticalup.ferrocene.dev">Read the
-   specification &raquo;</a></p>
+   documentation &raquo;</a></p>
 
 The CriticalUp Documentation (CUD) is a document describing the CriticalUp
 tool.
 
-The CriticalUp Documentation text is licensed under either the ``MIT``
-or ``Apache-2.0`` licenses, at your option. Individual files might have
-different licensing. Licensing metadata is present in each file, and the full
-licenses text is present in the ``LICENSES/`` directory.
-
-Building the specification
+Building the documentation
 ==========================
 
-CUD uses `Sphinx`_ to build a rendered version of the specification. To
-simplify building the rendered version, we created a script called ``make.py``
-that takes care of installing the expected Sphinx release and invoking it with
-the right flags.
+CUD uses `Sphinx`_ to build a rendered version of the specification, and `uv`_
+to install and manage Python dependencies (including Sphinx itself). To simplify
+building the rendered version, we created a script called ``make.py`` that takes
+care of invoking Sphinx with the right flags.
 
 You can build the rendered version by running::
 
@@ -56,25 +51,16 @@ This will clone the source code of the tool, build it, and execute it on the
 rendered documentation.
 
 .. _Sphinx: https://www.sphinx-doc.org
+.. _uv: https://docs.astral.sh/uv/
 
 Updating build dependencies
 ===========================
 
-The CUD uses ``pip-tools`` to manage the Python dependencies used for builds,
-as it allows pinning hashes for the dependencies. While it doesn't add any
-additional burden when installing dependencies (the format it outputs is
-understood by `pip`), you have to install it when regenerating the
-``requirements.txt`` file.
-
-To install `pip-tools`, we recommend first installing `pipx`_, and then
-running::
-
-   pipx install pip-tools
-
-Once that's done, you can change the list of desired dependencies in the
-``requirements.in`` file, and run this command to regenerate the
-``requirements.txt`` file::
+The CUD uses ``uv`` to manage the Python dependencies used for builds. If you
+change the list of dependencies in ``pyproject.toml`` they will automatically be
+installed the next time you run ``make.py``. If you want to update the packages
+in the lockfile, run::
 
-   pip-compile --generate-hashes
+   uv lock --upgrade
 
 .. _pipx: https://pypa.github.io/pipx/

docs/make.py

@@ -1,19 +1,8 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 # SPDX-FileCopyrightText: The Ferrocene Developers
 # SPDX-License-Identifier: MIT OR Apache-2.0
 
+import ferrocene_standalone_make_cli
 import os
-import subprocess
-import sys
 
-root = os.path.abspath(os.path.dirname(__file__))
-subprocess.run(
-    ["git", "submodule", "update", "--init"],
-    check=True,
-    cwd=root,
-)
-
-sys.path.insert(0, "shared")
-import make_common  # noqa: E402
-
-make_common.main(root)
+ferrocene_standalone_make_cli.main(os.path.abspath(os.path.dirname(__file__)))

docs/pyproject.toml

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# SPDX-FileCopyrightText: The Ferrocene Developers
+
+[project]
+name = "criticalup-docs"
+version = "0.0.0"
+
+requires-python = ">= 3.10"
+dependencies = [
+    "sphinx ~= 8.0",
+    "sphinx-autobuild >= 0", # Doesn't use semver.
+    "ferrocene-sphinx-shared-resources >= 0",
+    "myst_parser ~= 4.0.0"
+]

docs/src/conf.py

@@ -1,13 +1,6 @@
 # SPDX-FileCopyrightText: The Ferrocene Developers
 # SPDX-License-Identifier: MIT OR Apache-2.0
 
-# -- Path setup --------------------------------------------------------------
-
-import os
-import sys
-
-sys.path.append(os.path.abspath("../shared/exts"))
-
 
 # -- Project information -----------------------------------------------------
 
@@ -23,7 +16,6 @@
 # ones.
 extensions = [
     "ferrocene_toctrees",
-    "ferrocene_intersphinx_support",
     "ferrocene_qualification",
     "ferrocene_domain_cli",
     "myst_parser",