diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index e2359e9b6b..e40df5cae3 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -418,7 +418,7 @@ jobs: ${{ runner.os }}-uv- - name: Install Python Dependencies - run: uv sync --group ci --no-dev + run: uv sync --locked --group ci --no-dev - name: Add .venv to PATH run: echo "${GITHUB_WORKSPACE}/.venv/bin" >> "$GITHUB_PATH" @@ -426,6 +426,15 @@ jobs: - name: Build Docs run: tox -e docs + - name: Install PDF build dependencies + run: | + sudo DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \ + latexmk texlive-latex-recommended texlive-latex-extra \ + texlive-fonts-recommended tex-gyre xindy + + - name: Build PDF and EPUB + run: tox -e docs-formats + - name: Trigger ReadTheDocs build if: ${{ github.ref_name == 'trunk' }} env: diff --git a/.readthedocs.yml b/.readthedocs.yml index d4db84c410..eb49b9bdb8 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -15,7 +15,7 @@ build: create_environment: - python -m uv venv "${READTHEDOCS_VIRTUALENV_PATH}" install: - - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" python -m uv sync --frozen --group docs --no-dev + - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" python -m uv sync --locked --group docs --no-dev # Build documentation in the "docs/" directory with Sphinx sphinx: @@ -24,6 +24,3 @@ sphinx: formats: - pdf - epub - -# NOTE: We need to use older version of sphinx otherwise bullet points won't be rendered correctly -# on RTD using rtd theme. diff --git a/CHANGES.rst b/CHANGES.rst index 51d64604c5..03844169e2 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -2655,7 +2655,7 @@ Compute ~~~~~~~ - [ARM] Support OS disk size definition on node creation (#1196) - [Vojta Bartoš] + [Vojta Bartoš] - [Digital Ocean] Support floating IPs (#1177) [Rick van de Loo] diff --git a/docs/conf.py b/docs/conf.py index 4852097f97..f361b99c56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,11 +21,6 @@ from sphinx.ext import apidoc from sphinx.domains.python import PythonDomain -try: - import sphinx_rtd_theme -except ImportError: - sphinx_rtd_theme = None - BASE_DIR = os.path.dirname(os.path.abspath(__file__)) BASE_DIR = os.path.abspath(BASE_DIR) @@ -121,13 +116,6 @@ # a list of builtin themes. html_theme = "sphinx_rtd_theme" -if sphinx_rtd_theme: - html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -else: - html_theme = "default" - - # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. diff --git a/docs/development.rst b/docs/development.rst index f73e5bba36..5c304c5c45 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -51,6 +51,16 @@ If you also work on documentation, add the docs group: Commit ``uv.lock`` whenever dependency versions change. +Build the HTML documentation with ``uv run tox -e docs``. To also validate the +PDF and EPUB formats published on Read the Docs, run ``uv run tox -e docs-formats``. +PDF builds require ``make``, ``latexmk``, ``xindy``, the recommended and extra +LaTeX packages, and the recommended and TeX Gyre fonts. On Ubuntu, install these with: + +.. sourcecode:: bash + + sudo apt-get install make latexmk xindy texlive-latex-recommended \ + texlive-latex-extra texlive-fonts-recommended tex-gyre + General contribution guidelines ------------------------------- diff --git a/pyproject.toml b/pyproject.toml index a0f14af4a8..c2928e2a2f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -112,8 +112,8 @@ lint = [ docs = [ "rstcheck==6.2.5; python_version >= '3.10'", "fasteners", - "sphinx_rtd_theme==2.0.0", - "sphinx==6.2.1", + "sphinx_rtd_theme==3.1.0", + "sphinx==8.1.3", "pygments>=2.20.0,<3.0.0", ] mypy = [ diff --git a/tox.ini b/tox.ini index d37911c237..482e7ceb56 100644 --- a/tox.ini +++ b/tox.ini @@ -138,6 +138,15 @@ commands = rstcheck --report-level warning ../README.rst # TODO: Add -W back when we fix all the warnings in docstrings sphinx-build -j auto -b html -d {envtmpdir}/doctrees . _build/html +[testenv:docs-formats] +basepython = python3.12 +dependency_groups = + docs +changedir = docs +commands = python ../contrib/generate_provider_feature_matrix_table.py + sphinx-build -j auto -b epub -d {envtmpdir}/doctrees-epub . _build/epub + sphinx-build -M latexpdf . _build -j auto + [testenv:provider-tables] basepython: python3.12 commands = python ./contrib/generate_provider_feature_matrix_table.py diff --git a/uv.lock b/uv.lock index 9c2c2884d6..2bf5923d81 100644 --- a/uv.lock +++ b/uv.lock @@ -50,7 +50,6 @@ dev = [ { name = "fasteners" }, { name = "flake8" }, { name = "isort" }, - { name = "libvirt-python" }, { name = "mypy", marker = "implementation_name == 'cpython'" }, { name = "paramiko", marker = "platform_python_implementation != 'PyPy'" }, { name = "pep8" }, @@ -120,7 +119,6 @@ test = [ { name = "cryptography", version = "46.0.7", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "cryptography", version = "50.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "fasteners" }, - { name = "libvirt-python" }, { name = "paramiko", marker = "platform_python_implementation != 'PyPy'" }, { name = "pyopenssl", version = "26.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "pyopenssl", version = "26.4.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, @@ -149,7 +147,6 @@ dev = [ { name = "fasteners" }, { name = "flake8", specifier = "==5.0.4" }, { name = "isort", marker = "python_full_version >= '3.10'", specifier = "==6.0.1" }, - { name = "libvirt-python", specifier = "==12.0.0" }, { name = "mypy", marker = "python_full_version >= '3.10' and implementation_name == 'cpython'", specifier = "==1.15.0" }, { name = "paramiko", marker = "platform_python_implementation != 'PyPy'", specifier = "==5.0.0" }, { name = "pep8", specifier = "==1.7.1" }, @@ -161,7 +158,7 @@ dev = [ { name = "pytest-benchmark", extras = ["histogram"], marker = "python_full_version >= '3.10'", specifier = "==5.1.0" }, { name = "pytest-timeout", specifier = "==2.4.0" }, { name = "pytest-xdist", specifier = "==3.6.1" }, - { name = "pyupgrade", specifier = "==3.3.1" }, + { name = "pyupgrade", specifier = "==3.21.2" }, { name = "requests", specifier = ">=2.27.1" }, { name = "requests", specifier = ">=2.33.0" }, { name = "requests-mock", specifier = "==1.12.1" }, @@ -176,8 +173,8 @@ docs = [ { name = "fasteners" }, { name = "pygments", specifier = ">=2.20.0,<3.0.0" }, { name = "rstcheck", marker = "python_full_version >= '3.10'", specifier = "==6.2.5" }, - { name = "sphinx", specifier = "==6.2.1" }, - { name = "sphinx-rtd-theme", specifier = "==2.0.0" }, + { name = "sphinx", specifier = "==8.1.3" }, + { name = "sphinx-rtd-theme", specifier = "==3.1.0" }, ] integration-compute = [{ name = "bottle" }] integration-storage = [ @@ -199,7 +196,7 @@ lint = [ { name = "pep8", specifier = "==1.7.1" }, { name = "prek", specifier = ">=0.2.17" }, { name = "pylint", marker = "python_full_version >= '3.10'", specifier = "==4.0.9" }, - { name = "pyupgrade", specifier = "==3.3.1" }, + { name = "pyupgrade", specifier = "==3.21.2" }, { name = "requests", specifier = ">=2.27.1" }, { name = "rstcheck", marker = "python_full_version >= '3.10'", specifier = "==6.2.5" }, ] @@ -216,7 +213,6 @@ test = [ { name = "cryptography", marker = "python_full_version < '3.11'", specifier = "==46.0.7" }, { name = "cryptography", marker = "python_full_version >= '3.11'", specifier = "==50.0.0" }, { name = "fasteners" }, - { name = "libvirt-python", specifier = "==12.0.0" }, { name = "paramiko", marker = "platform_python_implementation != 'PyPy'", specifier = "==5.0.0" }, { name = "pyopenssl", marker = "python_full_version < '3.11'", specifier = "==26.0.0" }, { name = "pyopenssl", marker = "python_full_version >= '3.11'", specifier = "==26.4.0" }, @@ -960,11 +956,11 @@ wheels = [ [[package]] name = "docutils" -version = "0.19" +version = "0.21.2" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/6b/5c/330ea8d383eb2ce973df34d1239b3b21e91cd8c865d21ff82902d952f91f/docutils-0.19.tar.gz", hash = "sha256:33995a6753c30b7f577febfc2c50411fec6aac7f7ffeb7c4cfe5991072dcf9e6", size = 2056383, upload-time = "2022-07-05T20:17:31.045Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ae/ed/aefcc8cd0ba62a0560c3c18c33925362d46c6075480bfa4df87b28e169a9/docutils-0.21.2.tar.gz", hash = "sha256:3a6b18732edf182daa3cd12775bbb338cf5691468f91eeeb109deff6ebfa986f", size = 2204444, upload-time = "2024-04-23T18:57:18.24Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/93/69/e391bd51bc08ed9141ecd899a0ddb61ab6465309f1eb470905c0c8868081/docutils-0.19-py3-none-any.whl", hash = "sha256:5e1de4d849fee02c63b040a4a3fd567f4ab104defd8a5511fbbc24a8a017efbc", size = 570472, upload-time = "2022-07-05T20:17:26.388Z" }, + { url = "https://files.pythonhosted.org/packages/8f/d7/9322c609343d929e75e7e5e6255e614fcc67572cfd083959cdef3b7aad79/docutils-0.21.2-py3-none-any.whl", hash = "sha256:dafca5b9e384f0e419294eb4d2ff9fa826435bf15f15b7bd45723e8ad76811b2", size = 587408, upload-time = "2024-04-23T18:57:14.835Z" }, ] [[package]] @@ -1186,12 +1182,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/81/db/e655086b7f3a705df045bf0933bdd9c2f79bb3c97bfef1384598bb79a217/keyring-25.7.0-py3-none-any.whl", hash = "sha256:be4a0b195f149690c166e850609a477c532ddbfbaed96a404d4e43f8d5e2689f", size = 39160, upload-time = "2025-11-16T16:26:08.402Z" }, ] -[[package]] -name = "libvirt-python" -version = "12.0.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/5e/cd/a8fdd1c691f2a6a6dc8b0711b42473a7342e4d1a7a1e9ef90677a236eb73/libvirt_python-12.0.0.tar.gz", hash = "sha256:7b4de7d2dde2bc380cf4e108d1eeb8aad50beb3ae351ab9265a7fedc587742bc", size = 243300, upload-time = "2026-01-15T09:14:43.074Z" } - [[package]] name = "markdown-it-py" version = "4.0.0" @@ -2014,14 +2004,14 @@ wheels = [ [[package]] name = "pyupgrade" -version = "3.3.1" +version = "3.21.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "tokenize-rt" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/b4/e8/4c3f29d281a6dcf7ffe19a19a446fd385b34802b3b33d25ebcc5ec03d285/pyupgrade-3.3.1.tar.gz", hash = "sha256:f88bce38b0ba92c2a9a5063c8629e456e8d919b67d2d42c7ecab82ff196f9813", size = 43200, upload-time = "2022-12-06T22:20:02.168Z" } +sdist = { url = "https://files.pythonhosted.org/packages/7f/a1/dc63caaeed232b1c58eae1b7a75f262d64ab8435882f696ffa9b58c0c415/pyupgrade-3.21.2.tar.gz", hash = "sha256:1a361bea39deda78d1460f65d9dd548d3a36ff8171d2482298539b9dc11c9c06", size = 45455, upload-time = "2025-11-19T00:39:48.012Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/31/ee/dda0d7b86c4c0cd02494566243ad14f152e10994f1c345d57e9b9edd0c8a/pyupgrade-3.3.1-py2.py3-none-any.whl", hash = "sha256:3b93641963df022d605c78aeae4b5956a5296ea24701eafaef9c487527b77e60", size = 58472, upload-time = "2022-12-06T22:20:00.369Z" }, + { url = "https://files.pythonhosted.org/packages/16/8c/433dac11910989a90c40b10149d07ef7224232236971a562d3976790ec53/pyupgrade-3.21.2-py2.py3-none-any.whl", hash = "sha256:2ac7b95cbd176475041e4dfe8ef81298bd4654a244f957167bd68af37d52be9f", size = 62814, upload-time = "2025-11-19T00:39:46.958Z" }, ] [[package]] @@ -2297,7 +2287,7 @@ wheels = [ [[package]] name = "sphinx" -version = "6.2.1" +version = "8.1.3" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "alabaster" }, @@ -2316,24 +2306,25 @@ dependencies = [ { name = "sphinxcontrib-jsmath" }, { name = "sphinxcontrib-qthelp" }, { name = "sphinxcontrib-serializinghtml" }, + { name = "tomli", marker = "python_full_version < '3.11'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/0f/6d/392defcc95ca48daf62aecb89550143e97a4651275e62a3d7755efe35a3a/Sphinx-6.2.1.tar.gz", hash = "sha256:6d56a34697bb749ffa0152feafc4b19836c755d90a7c59b72bc7dfd371b9cc6b", size = 6681092, upload-time = "2023-04-25T11:01:40.914Z" } +sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/be0b61178fe2cdcb67e2a92fc9ebb488e3c51c4f74a36a7824c0adf23425/sphinx-8.1.3.tar.gz", hash = "sha256:43c1911eecb0d3e161ad78611bc905d1ad0e523e4ddc202a58a821773dc4c927", size = 8184611, upload-time = "2024-10-13T20:27:13.93Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/5f/d8/45ba6097c39ba44d9f0e1462fb232e13ca4ddb5aea93a385dcfa964687da/sphinx-6.2.1-py3-none-any.whl", hash = "sha256:97787ff1fa3256a3eef9eda523a63dbf299f7b47e053cfcf684a1c2a8380c912", size = 3024615, upload-time = "2023-04-25T11:01:08.562Z" }, + { url = "https://files.pythonhosted.org/packages/26/60/1ddff83a56d33aaf6f10ec8ce84b4c007d9368b21008876fceda7e7381ef/sphinx-8.1.3-py3-none-any.whl", hash = "sha256:09719015511837b76bf6e03e42eb7595ac8c2e41eeb9c29c5b755c6b677992a2", size = 3487125, upload-time = "2024-10-13T20:27:10.448Z" }, ] [[package]] name = "sphinx-rtd-theme" -version = "2.0.0" +version = "3.1.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "docutils" }, { name = "sphinx" }, { name = "sphinxcontrib-jquery" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/fe/33/2a35a9cdbfda9086bda11457bcc872173ab3565b16b6d7f6b3efaa6dc3d6/sphinx_rtd_theme-2.0.0.tar.gz", hash = "sha256:bd5d7b80622406762073a04ef8fadc5f9151261563d47027de09910ce03afe6b", size = 2785005, upload-time = "2023-11-28T04:14:03.104Z" } +sdist = { url = "https://files.pythonhosted.org/packages/84/68/a1bfbf38c0f7bccc9b10bbf76b94606f64acb1552ae394f0b8285bfaea25/sphinx_rtd_theme-3.1.0.tar.gz", hash = "sha256:b44276f2c276e909239a4f6c955aa667aaafeb78597923b1c60babc76db78e4c", size = 7620915, upload-time = "2026-01-12T16:03:31.17Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/ea/46/00fda84467815c29951a9c91e3ae7503c409ddad04373e7cfc78daad4300/sphinx_rtd_theme-2.0.0-py2.py3-none-any.whl", hash = "sha256:ec93d0856dc280cf3aee9a4c9807c60e027c7f7b461b77aeffed682e68f0e586", size = 2824721, upload-time = "2023-11-28T04:13:59.589Z" }, + { url = "https://files.pythonhosted.org/packages/87/c7/b5c8015d823bfda1a346adb2c634a2101d50bb75d421eb6dcb31acd25ebc/sphinx_rtd_theme-3.1.0-py2.py3-none-any.whl", hash = "sha256:1785824ae8e6632060490f67cf3a72d404a85d2d9fc26bce3619944de5682b89", size = 7655617, upload-time = "2026-01-12T16:03:28.101Z" }, ] [[package]]