ci: Fix doc dependency resolving (#475)

* uv somehow decides to constrain libraries to be compatible with the whole range of python versions supported by torchjd (3.10-3.13) when resolving, so it does not install libraries that require python 3.11+ for example, even when using python 3.13. This leads to outdated library versions installed in the CI and locally, especially documentation-related libraries.
* Adding --python-version=... forces uv to resolve libraries compatible with the specified python version only, fixing the issue
* When using `uv run ...`, uv automatically re-syncs. There's no way to specify the python-version for which to resolve when this happens, so the idea is to prevent this resyncing by either using --no-sync everytime we call uv run, or by using the UV_NO_SYNC=1 environment variable. This is done in both ci files that have a uv run, and it's now recommended in CONTRIBUTING.md
* Uncap furo (our sphinx theme): it just changes color of already-clicked links, which is not that bad IMO (and we can probably override this). It's also required for compatibility with more recent versions of other libraries.
* Increase lower cap of sphinx-autodoc-typehints. Before 3.5.0, it's not compatible with Python 3.14.

Author: ValerianRey

.github/workflows/build-deploy-docs.yml

@@ -6,6 +6,10 @@ on:
     tags:
       - 'v[0-9]*.[0-9]*.[0-9]*'
 
+env:
+  UV_NO_SYNC: 1
+  PYTHON_VERSION: '3.13'
+
 jobs:
   build-deploy-doc:
     name: Build & deploy doc
@@ -20,10 +24,10 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
         with:
-          python-version: '3.13'
+          python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Install dependencies (default with full options & doc)
-        run: uv pip install '.[full]' --group doc
+        run: uv pip install --python-version=${{ env.PYTHON_VERSION }} '.[full]' --group doc
 
       - name: Determine deployment folder
         id: deploy_folder

.github/workflows/release.yml

@@ -4,6 +4,9 @@ on:
   release:
     types: [published]
 
+env:
+  PYTHON_VERSION: 3.13
+
 jobs:
   pypi-publish:
     name: Publish to PyPI
@@ -19,7 +22,7 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
         with:
-          python-version: '3.13'
+          python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Build
         run: uv build

.github/workflows/tests.yml

@@ -6,6 +6,10 @@ on:
   schedule:
     - cron: '41 16 * * *'  # Every day at 16:41 UTC (to avoid high load at exact hour values).
 
+env:
+  UV_NO_SYNC: 1
+  PYTHON_VERSION: 3.13
+
 jobs:
   tests-full-install:
     name: Run tests with full install
@@ -23,7 +27,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install default (with full options) and test dependencies
-        run: uv pip install '.[full]' --group test
+        run: uv pip install --python-version=${{ matrix.python-version }} '.[full]' --group test
       - name: Run unit and doc tests with coverage report
         run: uv run pytest -W error tests/unit tests/doc --cov=src --cov-report=xml
       - name: Upload results to Codecov
@@ -39,9 +43,9 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
         with:
-          python-version: '3.13'
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: Install default (without any option) and test dependencies
-        run: uv pip install . --group test
+        run: uv pip install --python-version=${{ env.PYTHON_VERSION }} . --group test
       - name: Run unit and doc tests with coverage report
         run: |
           uv run pytest -W error tests/unit tests/doc \
@@ -64,10 +68,10 @@ jobs:
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
         with:
-          python-version: '3.13'
+          python-version: ${{ env.PYTHON_VERSION }}
 
       - name: Install dependencies (default with full options & doc)
-        run: uv pip install '.[full]' --group doc
+        run: uv pip install --python-version=${{ env.PYTHON_VERSION }} '.[full]' --group doc
 
       - name: Build Documentation
         working-directory: docs
@@ -83,10 +87,10 @@ jobs:
     - name: Set up uv
       uses: astral-sh/setup-uv@v5
       with:
-        python-version: '3.13'
+        python-version: ${{ env.PYTHON_VERSION }}
 
     - name: Install dependencies (default with full options & check)
-      run: uv pip install '.[full]' --group check
+      run: uv pip install --python-version=${{ env.PYTHON_VERSION }} '.[full]' --group check
 
     - name: Run mypy
       run: uv run mypy src/torchjd

CONTRIBUTING.md

@@ -19,7 +19,21 @@ mandatory, we only provide installation steps with this tool. You can install it
 2) Create a virtual environment and install the project in it. From the root of `torchjd`, run:
    ```bash
    uv venv
-   CC=gcc uv pip install -e '.[full]' --group check --group doc --group test --group plot
+   CC=gcc uv pip install --python-version=3.13.3 -e '.[full]' --group check --group doc --group test --group plot
+   ```
+   We also advise using `UV_NO_SYNC=1` to prevent `uv` from syncing all the time. This is because by
+   default, it tries to resolve libraries compatible with the whole range of Python versions
+   supported by TorchJD, but in reality, we just need an installation compatible with the currently
+   used Python version. That's also why we specify `--python-version=3.14` when running
+   `uv pip install`. To follow that recommendation, add the following line to your `.bashrc`:
+   ```bash
+   export UV_NO_SYNC=1
+   ```
+   and start a new terminal. The alternative is to use the `--no-sync` flag whenever you run a pip
+   command that would normally sync (like `uv run`).
+
+3) Install pre-commit:
+   ```bash
    uv run pre-commit install
    ```
 
@@ -46,7 +60,7 @@ from the root of `torchjd`:
 rm -rf .venv
 rm uv.lock
 uv venv
-CC=gcc uv pip install -e '.[full]' --group check --group doc --group test --group plot
+CC=gcc uv pip install --python-version=3.13.3 -e '.[full]' --group check --group doc --group test --group plot
 uv run pre-commit install
 ```
 

pyproject.toml

@@ -71,9 +71,9 @@ check = [
 
 doc = [
     "sphinx>=6.0, !=7.2.0, !=7.2.1, !=7.2.3, !=7.2.4, !=7.2.5",  # Versions in [7.2.0, 7.2.5] have a bug with an internal torch import from _C
-    "furo>=2023.0, <2024.04.27",  # Force it to be recent so that the theme looks better, 2024.04.27 seems to have bugged link colors
+    "furo>=2023.0",  # Force it to be recent so that the theme looks better
     "tomli>=1.1",  # The load function doesn't work similarly before 1.1
-    "sphinx-autodoc-typehints>=1.16.0",  # Some problems with TypeVars before 1.16
+    "sphinx-autodoc-typehints>=3.5.0",  # Bugged Union on Python 3.14 before 3.5.0
     "myst-parser>=3.0.1",  # Never tested lower versions
     "sphinx-design>=0.6.0",  # Never tested lower versions
 ]