From 3d34296b29435c82ec370532345336c4bedf1453 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 26 Jan 2025 20:53:15 +0200 Subject: [PATCH 1/6] Fix PR preview links (#215) --- .github/workflows/documentation-links.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/documentation-links.yml b/.github/workflows/documentation-links.yml index f05df37b..a4de7dcd 100644 --- a/.github/workflows/documentation-links.yml +++ b/.github/workflows/documentation-links.yml @@ -6,9 +6,6 @@ on: pull_request_target: types: - opened - paths: - - 'Doc/**' - - '.github/workflows/doc.yml' permissions: pull-requests: write From 01d5bcf0524663037ae68bbcea1248ce5238ce00 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Tue, 28 Jan 2025 01:40:31 +0000 Subject: [PATCH 2/6] Note minimum requirements for Sphinx (#216) --- .pre-commit-config.yaml | 14 +++++++------- README.md | 1 + pyproject.toml | 4 ++++ python_docs_theme/__init__.py | 2 ++ 4 files changed, 14 insertions(+), 7 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 071ad406..f9643647 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,17 +1,17 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.6.8 + rev: v0.9.3 hooks: - id: ruff args: [--exit-non-zero-on-fix] - repo: https://github.com/psf/black-pre-commit-mirror - rev: 24.8.0 + rev: 24.10.0 hooks: - id: black - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.6.0 + rev: v5.0.0 hooks: - id: check-case-conflict - id: check-merge-conflict @@ -22,24 +22,24 @@ repos: - id: trailing-whitespace - repo: https://github.com/python-jsonschema/check-jsonschema - rev: 0.29.2 + rev: 0.31.0 hooks: - id: check-dependabot - id: check-github-workflows - repo: https://github.com/rhysd/actionlint - rev: v1.7.2 + rev: v1.7.7 hooks: - id: actionlint - repo: https://github.com/tox-dev/pyproject-fmt - rev: 2.2.4 + rev: v2.5.0 hooks: - id: pyproject-fmt args: [--max-supported-python=3.13] - repo: https://github.com/abravalheri/validate-pyproject - rev: v0.20.2 + rev: v0.23 hooks: - id: validate-pyproject diff --git a/README.md b/README.md index f77b4910..24308f77 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Python Docs Sphinx Theme This is the theme for the Python documentation. +It requires Python 3.9 or newer and Sphinx 3.4 or newer. Note that when adopting this theme, you're also borrowing an element of the trust and credibility established by the CPython core developers over the diff --git a/pyproject.toml b/pyproject.toml index 9b7c60ff..1b34d905 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,6 +28,10 @@ classifiers = [ "Topic :: Documentation", "Topic :: Software Development :: Documentation", ] +dependencies = [ + "sphinx>=3.4", +] + urls.Code = "https://github.com/python/python-docs-theme" urls.Download = "https://pypi.org/project/python-docs-theme/" urls.Homepage = "https://github.com/python/python-docs-theme/" diff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.py index 0ee7d25d..295c1c53 100644 --- a/python_docs_theme/__init__.py +++ b/python_docs_theme/__init__.py @@ -53,6 +53,8 @@ def _html_page_context( def setup(app): + app.require_sphinx("3.4") + current_dir = os.path.abspath(os.path.dirname(__file__)) app.add_html_theme("python_docs_theme", current_dir) From 2f15ba657cba97c078a2b2869f1b387bfa24618e Mon Sep 17 00:00:00 2001 From: "Tomas R." Date: Mon, 3 Feb 2025 19:32:00 +0100 Subject: [PATCH 3/6] Horizontally centre the sidebar collapse button (#219) --- python_docs_theme/static/pydoctheme.css | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/python_docs_theme/static/pydoctheme.css b/python_docs_theme/static/pydoctheme.css index 0f6f8d37..bf92e92a 100644 --- a/python_docs_theme/static/pydoctheme.css +++ b/python_docs_theme/static/pydoctheme.css @@ -191,6 +191,9 @@ div.sphinxsidebar input[type='text'] { } #sidebarbutton { + display: flex; + justify-content: center; + align-items: center; /* Sphinx 4.x and earlier compat */ height: 100%; background-color: #CCCCCC; @@ -200,19 +203,12 @@ div.sphinxsidebar input[type='text'] { cursor: pointer; padding-top: 1px; float: right; - display: table; /* after Sphinx 4.x and earlier is dropped, only the below is needed */ width: 12px; border-radius: 0 5px 5px 0; border-left: none; } -#sidebarbutton span { - /* Sphinx 4.x and earlier compat */ - display: table-cell; - vertical-align: middle; -} - #sidebarbutton:hover { background-color: #AAAAAA; } From b6a1724264c4b4937d973eb73a0472ce9023e291 Mon Sep 17 00:00:00 2001 From: "Tomas R." Date: Tue, 4 Feb 2025 13:50:41 +0100 Subject: [PATCH 4/6] Make sidebar width more flexible (#218) --- python_docs_theme/static/pydoctheme.css | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/python_docs_theme/static/pydoctheme.css b/python_docs_theme/static/pydoctheme.css index bf92e92a..8b7b2cf8 100644 --- a/python_docs_theme/static/pydoctheme.css +++ b/python_docs_theme/static/pydoctheme.css @@ -140,6 +140,8 @@ span.pre { } div.sphinxsidebar { + display: flex; + width: min(25vw, 350px); float: none; position: sticky; top: 0; @@ -156,13 +158,17 @@ div.sphinxsidebar h4 { margin-top: 1.5em; } +div.bodywrapper { + margin-left: min(25vw, 350px); +} + div.sphinxsidebarwrapper { - width: 217px; box-sizing: border-box; height: 100%; overflow-x: hidden; overflow-y: auto; - float: left; + float: none; + flex-grow: 1; } div.sphinxsidebarwrapper > h3:first-child { @@ -202,9 +208,10 @@ div.sphinxsidebar input[type='text'] { font-size: 1.2em; cursor: pointer; padding-top: 1px; - float: right; + float: none; /* after Sphinx 4.x and earlier is dropped, only the below is needed */ width: 12px; + min-width: 12px; border-radius: 0 5px 5px 0; border-left: none; } @@ -485,7 +492,7 @@ div.genindex-jumpbox a { margin-inline-end: 0; } /* Remove sidebar and top related bar */ - div.related, .sphinxsidebar { + div.related, div.sphinxsidebar { display: none; } /* Anchorlinks are not hidden by fixed-positioned navbar when scrolled to */ From 482321225e574a6c09770a48196a9e4dd99f0b0b Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Tue, 4 Feb 2025 13:42:07 +0000 Subject: [PATCH 5/6] Set ``__version__`` in the runtime package (#222) * Set ``__version__`` in the runtime package * Return the version key in ``setup()`` * Add static type annotations to ``setup()`` * Fix the Python version for ``tomli`` * read ``__version__`` from ``__init__.py`` Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- CONTRIBUTING.rst | 2 +- babel_runner.py | 23 ++++++++++++++++++++--- pyproject.toml | 3 ++- python_docs_theme/__init__.py | 19 +++++++++++++------ requirements.txt | 2 +- 5 files changed, 37 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2533e96a..c85b77ca 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -2,7 +2,7 @@ How to release -------------- - Update ``CHANGELOG.rst`` -- Bump version (YYYY.MM) in ``pyproject.toml`` +- Bump version (YYYY.MM) in ``python_docs_theme/__init__.py`` - Commit - Push to check tests pass on `GitHub Actions `__ diff --git a/babel_runner.py b/babel_runner.py index da4001c7..ee5af161 100755 --- a/babel_runner.py +++ b/babel_runner.py @@ -3,6 +3,7 @@ from __future__ import annotations import argparse +import ast import subprocess from pathlib import Path @@ -17,6 +18,8 @@ ) from ie PROJECT_DIR = Path(__file__).resolve().parent +PYPROJECT_TOML = PROJECT_DIR / "pyproject.toml" +INIT_PY = PROJECT_DIR / "python_docs_theme" / "__init__.py" # Global variables used by pybabel below (paths relative to PROJECT_DIR) DOMAIN = "messages" @@ -29,9 +32,23 @@ def get_project_info() -> dict: """Retrieve project's info to populate the message catalog template""" - with open(Path(PROJECT_DIR / "pyproject.toml"), "rb") as f: - data = tomllib.load(f) - return data["project"] + pyproject_text = PYPROJECT_TOML.read_text(encoding="utf-8") + project_data = tomllib.loads(pyproject_text)["project"] + + # read __version__ from __init__.py + for child in ast.parse(INIT_PY.read_bytes()).body: + if not isinstance(child, ast.Assign): + continue + target = child.targets[0] + if not isinstance(target, ast.Name) or target.id != "__version__": + continue + version_node = child.value + if not isinstance(version_node, ast.Constant): + continue + project_data["version"] = version_node.value + break + + return project_data def extract_messages() -> None: diff --git a/pyproject.toml b/pyproject.toml index 1b34d905..7eb1cc2b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,6 @@ requires = [ [project] name = "python-docs-theme" -version = "2024.12" description = "The Sphinx theme for the CPython docs and related projects" readme = "README.md" license.file = "LICENSE" @@ -28,6 +27,8 @@ classifiers = [ "Topic :: Documentation", "Topic :: Software Development :: Documentation", ] +dynamic = [ "version" ] + dependencies = [ "sphinx>=3.4", ] diff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.py index 295c1c53..d8dd2c74 100644 --- a/python_docs_theme/__init__.py +++ b/python_docs_theme/__init__.py @@ -1,15 +1,22 @@ from __future__ import annotations import hashlib -import os from functools import cache from pathlib import Path -from typing import Any import sphinx.application from sphinx.builders.html import StandaloneHTMLBuilder -THEME_PATH = Path(__file__).parent.resolve() +TYPE_CHECKING = False +if TYPE_CHECKING: + from typing import Any + + from sphinx.application import Sphinx + from sphinx.util.typing import ExtensionMetadata + +__version__ = "2024.12" + +THEME_PATH = Path(__file__).resolve().parent @cache @@ -52,15 +59,15 @@ def _html_page_context( ) -def setup(app): +def setup(app: Sphinx) -> ExtensionMetadata: app.require_sphinx("3.4") - current_dir = os.path.abspath(os.path.dirname(__file__)) - app.add_html_theme("python_docs_theme", current_dir) + app.add_html_theme("python_docs_theme", str(THEME_PATH)) app.connect("html-page-context", _html_page_context) return { + "version": __version__, "parallel_read_safe": True, "parallel_write_safe": True, } diff --git a/requirements.txt b/requirements.txt index 18e6c17c..ad829d49 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,4 @@ setuptools Babel Jinja2 -tomli; python_version < "3.10" +tomli; python_version < "3.11" From 24ed1541324a8d94e5113b4116943aec0ec43681 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Tue, 4 Feb 2025 14:55:00 +0000 Subject: [PATCH 6/6] Prepare 2025.2 release (#223) --- CHANGELOG.rst | 12 ++++++++++++ python_docs_theme/__init__.py | 2 +- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 47eef33d..74b09cad 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,18 @@ Changelog ========= +`2025.2 `_ +--------------------------------------------------------------------------- + +- Note minimum requirements for Sphinx (#216) + Contributed by Adam Turner +- Horizontally centre the sidebar collapse button (#219) + Contributed by Tomas Roun +- Make sidebar width more flexible (#218) + Contributed by Tomas Roun +- Set ``__version__`` in the runtime package (#222) + Contributed by Adam Turner + `2024.12 `_ ----------------------------------------------------------------------------- diff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.py index d8dd2c74..5a84c840 100644 --- a/python_docs_theme/__init__.py +++ b/python_docs_theme/__init__.py @@ -14,7 +14,7 @@ from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata -__version__ = "2024.12" +__version__ = "2025.2" THEME_PATH = Path(__file__).resolve().parent