search

python / python-docs-theme

Sphinx theme for Python documentation
Other
75 stars 58 forks source link

How to deploy 2023.5 for 3.11 branch? #134

Closed hugovk closed 1 year ago

hugovk commented 1 year ago

We have the dark theme (https://github.com/python/python-docs-theme/pull/44) deployed on https://docs.python.org/3.12/ and https://docs.python.org/3.13/ and I think it's ready for https://docs.python.org/3/ 🚀

@JulienPalard What do we need to deploy on 3.11?

44 was merged in the latest 2023.5 release.

I checked requirements.txt in the 3.11 branch, but that has python-docs-theme>=2022.1 which would install the latest, but it mustn't be using this file:

https://github.com/python/cpython/blob/4f7c23e4dfb4b932b3916f8f79895e2a1bf3ae43/Doc/requirements.txt#L16-L18

I also checked but didn't find it in https://github.com/python/docsbuild-scripts

Where is the version pinned for each actual docs deploy?

Thanks!

JulienPalard commented 1 year ago

On docs.python.org it's all handled by docsbuild-scripts.

See https://github.com/python/docsbuild-scripts/blob/952c9ee85c676ec58a5126fb0d96a98e47f1f373/build_docs.py#L829, it "just" use the requirements.txt found in cpython's Doc/. Except when it cause trouble we override it here: https://github.com/python/docsbuild-scripts/blob/952c9ee85c676ec58a5126fb0d96a98e47f1f373/build_docs.py#L102

The venvs are kept from one build to another, so having >= in the requirements.txt file is not enough to have the theme bumped. To "bump" it I often rm -fr'ed the venv manually over ssh on the build server to have it fresh on the next build: this is not optimal.

One of the way to fix it would be to be more precise about which version of the theme we want in the cpython's Doc/requirements.txt file, but in the other hand this means that once a Python version is in security-only and EOL we have no way to bump its theme (except by overwriting it in docsbuild-script, which is already possible).

AA-Turner commented 1 year ago

Would the following change help at all?

-            [venv_path / "bin" / "python", "-m", "pip", "install"]
+            [venv_path / "bin" / "python", "-m", "pip", "install", "--upgrade"]

in build_docs.py#L838

JulienPalard commented 1 year ago

That should do it, yes.

hugovk commented 1 year ago

Thanks, please see PR https://github.com/python/docsbuild-scripts/pull/161.

hugovk commented 1 year ago

We could also consider removing the venv for each build, it only takes some 5s to recreate it locally with everything already in the pip cache.

I think other hosts such as Read the Docs, Netlify and GitHub Pages deploy to a clean slate.