experiment: migrate to uv as package manager

.gitattributes

@@ -5,6 +5,7 @@
 *.pdf binary
 *.png binary
 *.zip binary
+uv.lock binary
 
 # Unix-style line endings
 [attr]unix text eol=lf

.github/workflows/builddoc.yml

@@ -14,7 +14,7 @@ concurrency:
 
 env:
   FORCE_COLOR: "1"
-  UV_SYSTEM_PYTHON: "1"  # make uv do global installs
+  UV_VERSION: 0.5.14  # Pin the version of UV
 
 jobs:
   verbose:
@@ -24,21 +24,16 @@ jobs:
     - uses: actions/checkout@v4
       with:
         persist-credentials: false
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: "3"
     - name: Install graphviz
       run: sudo apt-get install --no-install-recommends --yes graphviz
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
-    - name: Install dependencies
-      run: uv pip install . --group docs
     - name: Render the documentation
       run: >
+        uv run
         sphinx-build
         -M html ./doc ./build/sphinx
         --verbose

.github/workflows/lint.yml

@@ -14,7 +14,7 @@ concurrency:
 
 env:
   FORCE_COLOR: "1"
-  UV_SYSTEM_PYTHON: "1"  # make uv do global installs
+  UV_VERSION: 0.5.14  # Pin the version of UV
 
 jobs:
   # If you update any of these commands, don't forget to update the equivalent
@@ -33,10 +33,10 @@ jobs:
         args: --version
 
     - name: Lint with Ruff
-      run: ruff check --output-format=github
+      run: uv run ruff check --output-format=github
 
     - name: Format with Ruff
-      run: ruff format --diff
+      run: uv run ruff format --diff
 
   mypy:
     runs-on: ubuntu-latest
@@ -45,19 +45,13 @@ jobs:
     - uses: actions/checkout@v4
       with:
         persist-credentials: false
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: "3"
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
-    - name: Install dependencies
-      run: uv pip install -r pyproject.toml --group package --group test --group types
     - name: Type check with mypy
-      run: mypy
+      run: uv run mypy
 
   pyright:
     runs-on: ubuntu-latest
@@ -73,7 +67,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install -r pyproject.toml --group package --group test --group types
@@ -94,7 +88,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install --group lint
@@ -115,7 +109,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install --group package

.github/workflows/main.yml

@@ -24,6 +24,7 @@ env:
   PYTHONDEVMODE: "1"  # -X dev
   PYTHONWARNDEFAULTENCODING: "1"  # -X warn_default_encoding
   UV_SYSTEM_PYTHON: "1"  # make uv do global installs
+  UV_VERSION: 0.5.14  # Pin the version of UV
 
 jobs:
   ubuntu:
@@ -39,8 +40,8 @@ jobs:
         - "3.13"
         - "3.13t"
         docutils:
-        - "0.20"
-        - "0.21"
+        - "0.20.0"
+        - "0.21.0"
 #        include:
 #        # test every supported Docutils version for the latest supported Python
 #        - python: "3.13"
@@ -65,18 +66,12 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
-    - name: Install dependencies
-      run: uv pip install . --group test
-      env:
-        UV_PYTHON: "python${{ matrix.python }}"
     - name: Install Docutils ${{ matrix.docutils }}
-      run: uv pip install --upgrade "docutils~=${{ matrix.docutils }}.0"
-      env:
-        UV_PYTHON: "python${{ matrix.python }}"
+      run: uv add "docutils~=${{ matrix.docutils }}"
     - name: Test with pytest
-      run: python -m pytest -n logical --dist=worksteal -vv --durations 25
+      run: uv run --python ${{ matrix.python }} pytest -n logical --dist=worksteal -vv --durations 25
       env:
         PYTHONWARNINGS: "error"  # treat all warnings as errors
 
@@ -176,7 +171,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install . --group test
@@ -205,7 +200,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install . --group test
@@ -240,7 +235,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install . --group test
@@ -273,7 +268,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: |
@@ -304,7 +299,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install . --group test
@@ -335,7 +330,7 @@ jobs:
     - name: Install uv
       uses: astral-sh/setup-uv@v6
       with:
-        version: latest
+        version: ${{ env.UV_VERSION }}
         enable-cache: false
     - name: Install dependencies
       run: uv pip install . --group test pytest-cov

doc/internals/contributing.rst

@@ -93,17 +93,24 @@ These are the basic steps needed to start developing on Sphinx.
       git clone https://github.com/<USERNAME>/sphinx
       cd sphinx
 
-#. Setup a virtual environment.
+#. Install the `UV package manager <https://docs.astral.sh/uv/>__.
 
-   This is not necessary for unit testing, thanks to :program:`tox`,
-   but it is necessary if you wish to run :program:`sphinx-build` locally
-   or run unit tests without the help of :program:`tox`:
+   See https://docs.astral.sh/uv/getting-started/installation/
 
-   .. code-block:: shell
+   UV will manage your development environment for you.
+   You can run commands inside your development environment
+   by prefixing them with `uv run`.
+
+   See the `UV documentation <https://docs.astral.sh/uv/guides/>`__ for more tips.
+
+   .. tip::
+
+      You can avoid prefixing with `uv run` by 'activating' your virtual environment:
 
-       virtualenv ~/.venv
-       . ~/.venv/bin/activate
-       pip install -e .
+      .. code-block:: shell
+
+         uv sync # create the virtualenv (if it doesn't already exist)
+         . ./.venv/bin/activate
 
 #. Create a new working branch. Choose any name you like.
 
@@ -163,8 +170,8 @@ Style and type checks can be run as follows:
 
 .. code-block:: shell
 
-    ruff check .
-    mypy
+   uv run ruff check .
+   uv run mypy
 
 
 Unit tests
@@ -175,33 +182,18 @@ Sphinx is tested using pytest_ for Python code and Jasmine_ for JavaScript.
 .. _pytest: https://docs.pytest.org/en/latest/
 .. _Jasmine: https://jasmine.github.io/
 
-To run Python unit tests, we recommend using :program:`tox`, which provides a number
-of targets and allows testing against multiple different Python environments:
-
-* To list all possible targets:
-
-  .. code-block:: shell
-
-     tox -av
-
 * To run unit tests for a specific Python version, such as Python 3.13:
 
   .. code-block:: shell
 
-     tox -e py313
+     uv run --python 3.13 pytest
 
-* Arguments to :program:`pytest` can be passed via :program:`tox`,
+* Arguments to :program:`pytest` can be passed,
   e.g., in order to run a particular test:
 
   .. code-block:: shell
 
-     tox -e py313 tests/test_module.py::test_new_feature
-
-You can also test by installing dependencies in your local environment:
-
-  .. code-block:: shell
-
-     pip install .[test]
+     uv run pytest tests/test_module.py::test_new_feature
 
 To run JavaScript tests, use :program:`npm`:
 
@@ -259,7 +251,7 @@ To build the documentation, run the following command:
 
 .. code-block:: shell
 
-   sphinx-build -M html ./doc ./build/sphinx --fail-on-warning
+   uv run sphinx-build -M html ./doc ./build/sphinx --fail-on-warning
 
 This will parse the Sphinx documentation's source files and generate HTML for
 you to preview in :file:`build/sphinx/html`.
@@ -271,7 +263,7 @@ To do so, use `sphinx-autobuild`_ to run the following command:
 
 .. code-block:: shell
 
-   sphinx-autobuild ./doc ./build/sphinx/
+   uv run sphinx-autobuild ./doc ./build/sphinx/
 
 .. _sphinx-autobuild: https://github.com/sphinx-doc/sphinx-autobuild