diff --git a/.github/workflows/documentation-links.yml b/.github/workflows/documentation-links.yml index f05df37..a4de7dc 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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 071ad40..f964364 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/CHANGELOG.rst b/CHANGELOG.rst index 47eef33..74b09ca 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/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2533e96..c85b77c 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/README.md b/README.md index f77b491..24308f7 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/babel_runner.py b/babel_runner.py index da4001c..ee5af16 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 9b7c60f..7eb1cc2 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,12 @@ classifiers = [ "Topic :: Documentation", "Topic :: Software Development :: Documentation", ] +dynamic = [ "version" ] + +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 0ee7d25..5a84c84 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__ = "2025.2" + +THEME_PATH = Path(__file__).resolve().parent @cache @@ -52,13 +59,15 @@ def _html_page_context( ) -def setup(app): - current_dir = os.path.abspath(os.path.dirname(__file__)) - app.add_html_theme("python_docs_theme", current_dir) +def setup(app: Sphinx) -> ExtensionMetadata: + app.require_sphinx("3.4") + + 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/python_docs_theme/static/pydoctheme.css b/python_docs_theme/static/pydoctheme.css index 0f6f8d3..8b7b2cf 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 { @@ -191,6 +197,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; @@ -199,20 +208,14 @@ div.sphinxsidebar input[type='text'] { font-size: 1.2em; cursor: pointer; padding-top: 1px; - float: right; - display: table; + 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; } -#sidebarbutton span { - /* Sphinx 4.x and earlier compat */ - display: table-cell; - vertical-align: middle; -} - #sidebarbutton:hover { background-color: #AAAAAA; } @@ -489,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 */ diff --git a/requirements.txt b/requirements.txt index 18e6c17..ad829d4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,4 @@ setuptools Babel Jinja2 -tomli; python_version < "3.10" +tomli; python_version < "3.11"