Update readthedocs builds to use tox with tox-uv #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
Use uv via tox-uv for speed

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.

Update: Split off doc dependency pinning

A chunk of this moved into #2219

The remainder, in this PR, is focused only on the RTD build config.

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).

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).

docs/requirements.in

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.

I'm not sure if I should make a change for this because of how the Python version flows through uv.

When uv installs tox+tox-uv, we have to specify a Python version to have control -- that's the 3.13 below.
tox-uv is then responsible for provisioning the environment under tox, so that's a uv invocation as well. I think that by default the current interpreter version is used, but I admit that I'm not 100% certain how that gets decided.

Well, this change would need to be integrated in different places. But it's not in the scope of this PR so I'm marking the thread as resolved. This is something to tackle in the future.

docs/requirements.txt

.readthedocs.yaml

tox.ini

.readthedocs.yaml

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 · 2025-09-19T04:06:39Z

I've come back to this to start trying to clean it up. I retitled, updated the initial doc to indicate that the PR was split up, and removed the skip-changelog labels.

I think we should drop the htmlzip and pdf format docs, which is what's currently done here. They're much less used, and I want the toolchain all aligned so that what we can test locally matches RTD. But that probably needs a changelog note -- not sure why I didn't think so before.

I'm about to start the rebase... 🤞 that goes smoothly

- 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

- Don't `git fetch --unshallow` twice - Do the `git` steps in `commands_pre` Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>

webknjaz

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

sirosen changed the title ~~Update doc builds to pin the 'pip' version and use tox in readthedocs~~ Update readthedocs builds to use tox with tox-uv Sep 19, 2025

sirosen removed skip-changelog Avoid listing in changelog bot:chronographer:skip labels Sep 19, 2025

sirosen force-pushed the update-rtd-config branch from c84a42c to 7835f0c Compare September 19, 2025 04:27

sirosen added a commit to sirosen/pip-tools that referenced this pull request Sep 19, 2025

Add news fragment for jazzband#2218

a0fd8d4

psf-chronographer bot added the bot:chronographer:provided label Sep 19, 2025

sirosen and others added 4 commits September 25, 2025 16:22

Use 'asdf' to install 'uv' in RTD builds

a6c7a0f

Add news fragment for jazzband#2218

cd1cd0f

Adjust git usage in doc build contexts

76d4a85

- Don't `git fetch --unshallow` twice - Do the `git` steps in `commands_pre` Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>

sirosen force-pushed the update-rtd-config branch from f24e46f to 76d4a85 Compare September 25, 2025 21:22

webknjaz approved these changes Sep 26, 2025

View reviewed changes

webknjaz added this pull request to the merge queue Sep 26, 2025

Merged via the queue into jazzband:main with commit d3eed27 Sep 26, 2025
43 checks passed

sirosen deleted the update-rtd-config branch September 26, 2025 03:43

Uh oh!

Update readthedocs builds to use tox with tox-uv #2218

Update readthedocs builds to use tox with tox-uv #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

Update: Split off doc dependency pinning

Contributor checklist

Maintainer checklist

Uh oh!

webknjaz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

webknjaz Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

sirosen Sep 19, 2025

Choose a reason for hiding this comment

Uh oh!

webknjaz Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

webknjaz Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

webknjaz Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

sirosen Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

webknjaz commented Aug 19, 2025

Uh oh!

sirosen commented Aug 19, 2025

Uh oh!

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

Uh oh!

Uh oh!

webknjaz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sirosen commented Aug 4, 2025 •

edited

Loading

sirosen commented Sep 19, 2025 •

edited

Loading