Update doc builds to pin the 'pip' version and use tox in readthedocs #2218

sirosen · 2025-08-04T04:17:57Z

No changelog needed. This is a set of minor infrastructure tweaks.

Pin the version of 'pip' in doc builds to 25.1
Update readthedocs builds to use tox

Notes

I used uv for the installation on the RTD worker to see how much faster it might be. The reported runtime on this PR was 22s, vs 44s on the last success on main. I'm generally happy using tox + tox-uv because it's faster and easy to remove uv if it ever causes a problem.
This failed the chronographer check, so I marked it with the default bot:chronographer:skip label (newly defined). I think we can simply update our docs to list this and we'll be good. Or we can create a chronographer config -- but I'd rather stick with the defaults unless we have a strong need.

Contributor checklist

Included tests for the changes.
A change note is created in changelog.d/ (see changelog.d/README.md for instructions) or the PR text says "no changelog needed".

Maintainer checklist

If no changelog is needed, apply the skip-changelog label.
Assign the PR to an existing or new milestone for the target version (following Semantic Versioning).

Doc building currently fails on the latest pip version (25.2). Declare `pip` as a doc dependency and pin it to 25.1.

- Update to `uv` + `tox` + `tox-uv` as the toolchain installed on the RTD worker. This treats `uv` as a way to improve the speed of the CI process without relying on any tool-specific features. - Update tox config slightly to suit RTD usage - Drop the 'pdf' and 'htmlzip' outputs - Update RTD builds to use Python 3.13

webknjaz

No changelog needed. This is a set of minor infrastructure tweaks.

@sirosen I would argue that this is exactly what the contrib change note type is intended for. These are changes that may challenge the contributors' understanding of how RTD is set up, the role of uv in there et al. But if you feel differently, we can keep it out.

I used uv for the installation on the RTD worker to see how much faster it might be. The reported runtime on this PR was 22s, vs 44s on the last success on main. I'm generally happy using tox + tox-uv because it's faster and easy to remove uv if it ever causes a problem.

Ack, although, there's some tweaks needed to make it integrated better.

This failed the chronographer check, so I marked it with the default bot:chronographer:skip label (newly defined). I think we can simply update our docs to list this and we'll be good. Or we can create a chronographer config -- but I'd rather stick with the defaults unless we have a strong need.

Due to historical reasons, I've kept this default in the bot (it's also more generic). However, a lot of projects have it as skip changelog or skip news. And it's best to integrate it with the existing label. Otherwise, we'll end up having to apply a tightly coupled pair of labels. This is going to be inconsistent whenever somebody else applies a label. Alternatively, we could migrate to the bot's label, getting rid of skip-changelog. Though, I know some people weren't happy with the naming in various projects.

Additionally, we still need the config to point to instructions on RTD from the checks page (https://github.com/jazzband/pip-tools/pull/2218/checks?check_run_id=47304029072).

webknjaz · 2025-08-04T09:52:17Z

docs/requirements.in

+# pip itself is a requirement, so that we keep the version of it pinned
+# for build consistency
+pip


I don't think that pip is a direct dependency of the docs infra, though. pip-tools is. I'd expect this to be something like

Suggested change

# pip itself is a requirement, so that we keep the version of it pinned

# for build consistency

pip

.

This is because

skip_install = false in tox.ini — piptools is being installed, along with all of its dependency tree, not just pip.

sphinxcontrib.apidoc is integrated in conf.py (it calls sphinx.ext.autodoc under the hood). This extension effectively imports everything under piptools and such imports will fail if the docs venv doesn't have every transitive dep of pip-tools.

The previous RTD config was set up to do pip install . directly.

With the above in mind, we should be producing a complete "lock file" as pip constraints in docs/requirements.txt, not just include pip in there, but also all the rest.

Yeah, pip isn't a direct dependency.

I think the breakage is caused by sphinx autodoc picking up some changed data from this class, which inherits from a pip-provided class. So we need the version of pip controlled in docs because it's a dependency of pip-tools.

I'd like to set skip_install = true and rely on the requirements data all being in docs/requirements.txt. I'll put this up in my separate PR for the requirements data only and we can discuss.

Yes, that's my understanding of the root cause as well.

I don't normally do a skip_install and try to go for -c instead..

webknjaz · 2025-08-04T09:56:38Z

.readthedocs.yaml

-    python: >-
-      3.11


This should be kept for reproducibility. Eventually, it should become the source of truth for all the docs building envs. Similar to what Hynek has here: https://github.com/hynek/stamina/blob/4832a081aacce48879fd770f9ace02efdf3aa10c/noxfile.py#L43-L47.

webknjaz · 2025-08-04T09:57:07Z

docs/requirements.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
+# This file is autogenerated by pip-compile with Python 3.12


Can we keep using the same runtime for now and then perform a bump separately?

Yes, this is just an artifact of my default runtime being 3.12 right now, and we're not setting base_python in the tox environment for pip-compile-docs. So if I forget to set it explicitly to 3.11, this happens. Should we set base_python = python3.11 in tox?

I'm not sure. I feel like that's going stale over time. I don't like having many hardcoded places for the same data. Let's not change it for now.

webknjaz · 2025-08-04T09:59:50Z

.readthedocs.yaml

+    # - Python 3.13
+    # - tox (with tox-uv)
+    - curl -LsSf https://astral.sh/uv/install.sh | sh
+    - ~/.local/bin/uv tool install tox --with tox-uv -p "3.13" --managed-python


I only noticed now that this attempts using Python 3.13 while the deptree is pinned with Python 3.12, while it used to be Python 3.11.

We should settle on having a single machine-readable runtime config to use in all places.

Additionally, could you use a long version of -p here?

webknjaz · 2025-08-04T10:03:38Z

.readthedocs.yaml

+    # install uv and use it to get
+    # - Python 3.13
+    # - tox (with tox-uv)
+    - curl -LsSf https://astral.sh/uv/install.sh | sh


I'm not happy about the curl | sh pattern in here. Can't we just use asdf or whatever other dep management tooling is pre-installed in the VMs?

Yeah, we can do it pretty easily with asdf. We can also use the provided virtualenv and pip install uv as a way of getting it.

Whatever's fastest I guess..

webknjaz · 2025-08-04T10:05:33Z

.readthedocs.yaml

+    # a complete clone is needed for setuptools-scm, and this is the method recommended by RTD
+    # ( https://rtd-with-docsearch.readthedocs.io/en/latest/build-customization.html#unshallow-git-clone )
+    - git fetch --unshallow || true


This is already included in the tox env. No need to duplicate the effort.

Suggested change

# a complete clone is needed for setuptools-scm, and this is the method recommended by RTD

# ( https://rtd-with-docsearch.readthedocs.io/en/latest/build-customization.html#unshallow-git-clone )

- git fetch --unshallow || true

webknjaz · 2025-08-04T10:07:26Z

tox.ini

Could you also move git fetch commands around line 76 into commands_pre? I've been doing this everywhere but haven't synced this project, it seems. Although, we could do this separately as it'd affect other docs envs as well...

webknjaz · 2025-08-04T10:09:52Z

.readthedocs.yaml

-formats:
-  - pdf
-  - htmlzip


So we're loosing these with the update. That's another thing we could mention in the change note.
Alternatively, we could try reproducing the same commands that RTD injects to get these outputs.

webknjaz · 2025-08-04T10:23:58Z

tox.ini

-  \t$ python3 -m http.server --directory \
-  \N\{QUOTATION MARK\}\{docs_dir\}\N\{QUOTATION MARK\} 0\n\n" +\
-  "=" * 120)'
+    {posargs:{envdir}/docs_out}


I see you didn't migrate the -t is_unversioned bit. This is fine for now as it's out of the scope, but would be good to do in a follow-up. It's particularly useful when setuptools-scm is used as the version string being dynamic prevents Sphinx from reusing cache and we can optimize it by setting it to something static in local dev envs.

webknjaz · 2025-08-04T10:35:50Z

docs/requirements.txt

Perhaps, we could decouple reconfiguring docs/requirements.* from changing the RTD integration? docs/requirements.txt is already integrated into both places so fixing it being incomplete would be an atomic change by itself. And it'd unblock any other PRs that may be happening in parallel, while we polish the integration bits.

Yeah, let me split it off. That's the part that I felt didn't need a changelog entry.
But I agree that some of the other bits may warrant a contrib note.

webknjaz · 2025-08-19T14:35:42Z

@sirosen does this need a rebase?

sirosen · 2025-08-19T15:44:44Z

I've been meaning to get back to some of the other work in pip-tools, but I forgot entirely about this particular PR. I think a rebase and some basic cleanup is something I can do here after my workday. I should re-title the PR as well, seeing as I split #2219 from this.

sirosen added 2 commits August 3, 2025 23:02

Pin the version of 'pip' in doc builds to 25.1

6c52646

Doc building currently fails on the latest pip version (25.2). Declare `pip` as a doc dependency and pin it to 25.1.

sirosen added skip-changelog Avoid listing in changelog bot:chronographer:skip labels Aug 4, 2025

webknjaz reviewed Aug 4, 2025

View reviewed changes

sirosen mentioned this pull request Aug 4, 2025

Pin pip-tools' dependencies for "build-docs" #2219

Merged

4 tasks

	# a complete clone is needed for setuptools-scm, and this is the method recommended by RTD
	# ( https://rtd-with-docsearch.readthedocs.io/en/latest/build-customization.html#unshallow-git-clone )
	- git fetch --unshallow \|\| true

Uh oh!

Update doc builds to pin the 'pip' version and use tox in readthedocs #2218

Are you sure you want to change the base?

Update doc builds to pin the 'pip' version and use tox in readthedocs #2218

Uh oh!

Conversation

sirosen commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notes

Contributor checklist

Maintainer checklist

Uh oh!

webknjaz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

webknjaz commented Aug 19, 2025

Uh oh!

sirosen commented Aug 19, 2025

Uh oh!

Uh oh!

sirosen commented Aug 4, 2025 •

edited

Loading