diff --git a/.babel.cfg b/.babel.cfg new file mode 100644 index 00000000..cc4c9de0 --- /dev/null +++ b/.babel.cfg @@ -0,0 +1,3 @@ +[javascript: **.js] + +[jinja2: **.html] diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..8452ef07 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,12 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: monthly + assignees: + - "ezio-melotti" + groups: + actions: + patterns: + - "*" diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 00000000..9d1e0987 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,5 @@ +changelog: + exclude: + authors: + - dependabot + - pre-commit-ci diff --git a/.github/workflows/documentation-links.yml b/.github/workflows/documentation-links.yml new file mode 100644 index 00000000..a4de7dcd --- /dev/null +++ b/.github/workflows/documentation-links.yml @@ -0,0 +1,24 @@ +name: Read the Docs PR preview +# Automatically edits a pull request's descriptions with a link +# to the documentation's preview on Read the Docs. + +on: + pull_request_target: + types: + - opened + +permissions: + pull-requests: write + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "python-docs-theme-previews" + single-version: "true" diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 00000000..88c0c7cb --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,20 @@ +name: Lint + +on: [push, pull_request, workflow_dispatch] + +env: + FORCE_COLOR: 1 + +permissions: + contents: read + +jobs: + lint: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + - uses: pre-commit/action@v3.0.1 diff --git a/.github/workflows/pypi-package.yml b/.github/workflows/pypi-package.yml new file mode 100644 index 00000000..744d49bd --- /dev/null +++ b/.github/workflows/pypi-package.yml @@ -0,0 +1,52 @@ +name: Build & maybe upload PyPI package + +on: + push: + pull_request: + release: + types: + - published + workflow_dispatch: + +permissions: + contents: read + +env: + FORCE_COLOR: 1 + +jobs: + # Always build & lint package. + build-package: + name: Build & verify package + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - uses: hynek/build-and-inspect-python-package@v2 + + # Upload to real PyPI on GitHub Releases. + release-pypi: + name: Publish to PyPI + environment: release-pypi + # Only run for published releases. + if: | + github.repository_owner == 'python' + && github.event.action == 'published' + runs-on: ubuntu-latest + needs: build-package + + permissions: + id-token: write + + steps: + - name: Download packages built by build-and-inspect-python-package + uses: actions/download-artifact@v4 + with: + name: Packages + path: dist + + - name: Upload package to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + attestations: true diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 00000000..23e6c7e6 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,89 @@ +name: Tests + +on: [push, pull_request, workflow_dispatch] + +env: + FORCE_COLOR: 1 + +jobs: + build_doc: + name: Build CPython docs + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + branch: ["3.14", "3.13", "3.12"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.branch }} + allow-prereleases: true + cache: pip + - name: Clone docsbuild scripts + run: | + git clone https://github.com/python/docsbuild-scripts/ + - name: Set up requirements + run: | + python -m pip install --upgrade pip + python -m pip install -r docsbuild-scripts/requirements.txt + - name: Build documentation + run: > + python ./docsbuild-scripts/build_docs.py + --quick + --build-root ./build_root + --www-root ./www + --log-directory ./logs + --group "$(id -g)" + --skip-cache-invalidation + --theme "$(pwd)" + --languages en + --branches ${{ matrix.branch }} + ${{ matrix.branch == '3.14' && '--select-output no-html' || '' }} + - name: Show logs + if: failure() + run: | + cat ./logs/docsbuild.log + - name: Upload + uses: actions/upload-artifact@v4 + with: + name: doc-html-${{ matrix.branch }} + path: www/ + + translations: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: ["ubuntu-latest", "windows-latest"] + # Test minimum supported and latest stable from 3.x series + python-version: ["3.12", "3"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + allow-prereleases: true + cache: pip + - name: Install dependencies + run: | + pip install --upgrade pip + pip install -r requirements.txt + - name: Remove locale file for testing + shell: bash + run: rm -rf locales/pt_BR/ + - run: python babel_runner.py extract + - run: python babel_runner.py init -l pt_BR + - run: python babel_runner.py update + - run: python babel_runner.py update -l pt_BR + - run: python babel_runner.py compile + - run: python babel_runner.py compile -l pt_BR + - name: Print .pot file + shell: bash + run: cat locales/messages.pot + - name: Print .po file + shell: bash + run: cat locales/pt_BR/LC_MESSAGES/messages.po + - name: list files in locales dir + shell: bash + run: ls -R locales/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..9a7e83b3 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,51 @@ +repos: + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.9.3 + hooks: + - id: ruff + args: [--exit-non-zero-on-fix] + + - repo: https://github.com/psf/black-pre-commit-mirror + rev: 24.10.0 + hooks: + - id: black + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: check-case-conflict + - id: check-merge-conflict + - id: check-toml + - id: check-yaml + - id: debug-statements + - id: end-of-file-fixer + - id: trailing-whitespace + + - repo: https://github.com/python-jsonschema/check-jsonschema + rev: 0.31.0 + hooks: + - id: check-dependabot + - id: check-github-workflows + + - repo: https://github.com/rhysd/actionlint + rev: v1.7.7 + hooks: + - id: actionlint + + - repo: https://github.com/tox-dev/pyproject-fmt + rev: v2.5.0 + hooks: + - id: pyproject-fmt + + - repo: https://github.com/abravalheri/validate-pyproject + rev: v0.23 + hooks: + - id: validate-pyproject + + - repo: meta + hooks: + - id: check-hooks-apply + - id: check-useless-excludes + +ci: + autoupdate_schedule: quarterly diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..7ac1f464 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,15 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# Project page: https://readthedocs.org/projects/python-docs-theme-previews/ + +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3" + + commands: + - git clone --depth=1 https://github.com/python/cpython + - make html CPYTHON_PATH=cpython + - mv cpython/Doc/build _readthedocs diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 00000000..fb43a9f1 --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1,235 @@ +Changelog +========= + +`2025.4.1 `_ +------------------------------------------------------------------------------- + +* Fix copy button with multiple tracebacks by @tomasr8 in https://github.com/python/python-docs-theme/pull/240 + +`2025.4 `_ +--------------------------------------------------------------------------- + +* Require Sphinx 7.3 by @AA-Turner in https://github.com/python/python-docs-theme/pull/221 +* Add support for Python 3.14 by @hugovk https://github.com/python/python-docs-theme/pull/236 +* Drop support for Python 3.10 and 3.11 by @hugovk in https://github.com/python/python-docs-theme/pull/234 +* Add a copy button to code samples by @tomasr8 in https://github.com/python/python-docs-theme/pull/231 +* Add missing i18n for copy button titles by @tomasr8 in https://github.com/python/python-docs-theme/pull/225 +* Use consistent line-height for light & dark theme by @tomasr8 in https://github.com/python/python-docs-theme/pull/227 +* Remove self-closing tags by @hugovk in https://github.com/python/python-docs-theme/pull/226 +* Replace deprecated classifier with licence expression (PEP 639) by @hugovk in https://github.com/python/python-docs-theme/pull/237 + +`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 `_ +----------------------------------------------------------------------------- + +- Hide header and search bar when printing (#204) + Contributed by Hugo van Kemenade + +`2024.10 `_ +----------------------------------------------------------------------------- + +- Add support for Python 3.13 (#196) + Contributed by Hugo van Kemenade +- Drop support for Python 3.8 (#197) + Contributed by Hugo van Kemenade +- Add script for handling translations (#195) + Contributed by Rafael Fontenelle +- Generate digital attestations for PyPI (PEP 740) (#198) + Contributed by Hugo van Kemenade + +`2024.6 `_ +--------------------------------------------------------------------------- + +- Add backgrounds and borders to admonitions (#190) + Contributed by Hugo van Kemenade +- Use different colour for 'Return value: Borrowed reference' (#188) + Contributed by Hugo van Kemenade + +`2024.4 `_ +--------------------------------------------------------------------------- + +- Add colour to version change directives (#185) + Contributed by Hugo van Kemenade +- Only show 'Last updated on ...' when ``last_updated`` defined (#183) + Contributed by Hugo van Kemenade +- Use system font stack for all code (#186) + Contributed by Hugo van Kemenade + +`2024.3 `_ +--------------------------------------------------------------------------- + +- Modernise font: use system font stack to improve text readability and webpage performance (#174) + Contributed by Hugo van Kemenade +- Remove incorrect CSS property (#178) + Contributed by Kerim Kabirov + +`2024.2 `_ +--------------------------------------------------------------------------- + +- Do not underline navigation links (#169) + Contributed by Hugo van Kemenade +- Only apply underline offset to code formatting for underline visibility (#171) + Contributed by Hugo van Kemenade + +`2024.1 `_ +--------------------------------------------------------------------------- + +- Underline links for readability and a11y (#160, #166) + Contributed by Hugo van Kemenade +- Add ``hosted_on`` variable for a link in the footer (#165) + Contributed by Hugo van Kemenade +- Consistently reference ``theme_root_icon`` (#163) + Contributed by Marko Budiselic +- Dark mode: fix contrast of footer highlight (#162) + Contributed by Hugo van Kemenade + +`2023.9 `_ +--------------------------------------------------------------------------- + +- Focus search box when pressing slash (#153) + Contributed by Hugo van Kemenade + +`2023.8 `_ +--------------------------------------------------------------------------- + +- Add Python 3.12 and 3.13 classifiers (#147) + Contributed by Hugo van Kemenade +- Dark mode: Also give aside.topic a dark background (#150) + Contributed by Hugo van Kemenade +- Restore the menu on mobile devices (inadvertently broken in 2023.7) (#146) + Contributed by Hugo van Kemenade + +`2023.7 `_ +--------------------------------------------------------------------------- + +- Fix compatibility with Sphinx 7.1 (#137) + Contributed by Pradyun Gedam +- Enable the slash keypress to focus the search field (#141) + Contributed by Mike Fiedler +- Sphinx 6.2 fix: add ``nav.contents`` where ``div.topic`` is used (#138) + Contributed by Hugo van Kemenade +- Dark mode: fix contrast for C++ specific styling (#133) + Contributed by Hugo van Kemenade +- Don't let long code literals extend beyond the right side of the screen (#139) + Contributed by Hugo van Kemenade +- Test with Python 3.12 (#140) + Contributed by Hugo van Kemenade + +`2023.5 `_ +--------------------------------------------------------------------------- + +- Add a dark theme. (#44) + Contributed by Nils K +- Fix: Remove searchbox id from form. (fixes #117) + Contributed by Nils K +- Update ``python-docs-theme`` to work with Sphinx 5 & 6. (#99 & #127) + Contributed by Adam Turner +- Override font for ``.sig`` for consistency with other code blocks. (#121) + Contributed by Chris Warrick +- Dark mode: add class to invert image brightness. (#128) + Contributed by Hugo van Kemenade + + +`2023.3.1 `_ +------------------------------------------------------------------------------- + +- Skip cache-busting for old Sphinx #113 + + +`2023.3 `_ +--------------------------------------------------------------------------- + +- Fix problem with monospace rendering in Vivaldi #104 +- Fix mobile nav obstructing content #96 +- Reduce footer margin only for desktop #106 +- Append a hash ?digest to CSS files for cache-busting #108 + + +`2022.1 `_ +---------------------------------------------------------------------------- + +- Add a configuration for license URL. (#90) +- Exclude the floating navbar from CHM help. (#84) +- Make sidebar scrollable and sticky (on modern browsers) (#91) + + +`2021.11.1 `_ +---------------------------------------------------------------------------------- + +- Fix monospace again, on buggy Google Chrome (#87) + Contributed by Tushar Sadhwani + + +`2021.11 `_ +------------------------------------------------------------------------------ + +- Fix monospace on buggy Google Chrome (#85) + Contributed by Tushar Sadhwani + + +`2021.8 `_ +----------------------------------------------------------------------------- + +- Add the copyright_url variable in the theme (#67) + Contributed by jablonskidev +- Improve readability (#79) + Contributed by Olga Bulat +- Remove #searchbox on mobile to fix a layout bug (#76) + Contributed by Olga Bulat +- Fix the appearance of version/language selects (#74) + Contributed by Olga Bulat + + +`2021.5 `_ +----------------------------------------------------------------------------- + +- Make the theme responsive (#46) + Contributed by Olga Bulat. +- Use Python 3.8 for the Github Actions (#71) + Contributed by Stéphane Wirtel. +- Use default pygments theme (#68) + Contributed by Aaron Carlisle. +- Test Github action to validate the theme against docsbuild scripts. (#69) + Contributed by Julien Palard. +- Add the copy button to pycon3 highlighted code blocks. (#64) + Contributed by Julien Palard. + + +`2020.12 `_ +------------------------------------------------------------------------------ + +- Updated the readme, to remind user to install the package in a virtual environment. (#41) + Contributed by Mariatta. +- Updated the package url, using the GitHub repository instead of docs.python.org (#49) + Contributed by Pradyun Gedam. +- Added license information to the footer of the doc (#36) + Contributed by Todd. +- Fixed typo in the footer (#52) + Contributed by Dominic Davis-Foster. +- Added information on how to use the package (#32) + Contributed by Tapasweni Pathak. +- Fixed code formatting (#53). + Contributed by Hugo van Kemenade. +- Fixed code bgcolor and codetextcolor for Sphinx 3.1.0+ (#57) + Contributed by Zhiming Wang. + +2018.7 +------ +Corresponds to `44a8f30 `_ + + +`2018.2 `_ +--------------------------------------------------------------------------- + +Initial release. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..c85b77ca --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,28 @@ +How to release +-------------- + +- Update ``CHANGELOG.rst`` +- Bump version (YYYY.MM) in ``python_docs_theme/__init__.py`` +- Commit +- Push to check tests pass on + `GitHub Actions `__ +- Go to https://github.com/python/python-docs-theme/releases +- Click "Draft a new release" +- Click "Choose a tag" +- Type the next YYYY.MM version (no leading zero) and + select "**Create new tag: YYYY.MM** on publish" +- Leave the "Release title" blank (it will be autofilled) +- Click "Generate release notes" and amend as required +- Click "Publish release" +- Check the tagged `GitHub Actions build `__ + has deployed to `PyPI `__ + +Makefile usage +-------------- + +This project includes a simple Makefile for syncing changes to the theme with +the main CPython repository. Run ``make help`` for details on available rules. + +There is one configurable variable, ``CPYTHON_PATH``, which should be the path +to the CPython repository on your machine. By default, it points to +``../cpython``. diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 3ae74ecc..00000000 --- a/MANIFEST.in +++ /dev/null @@ -1,2 +0,0 @@ -include LICENSE README.rst -recursive-include python_docs_theme *.* diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..bae89325 --- /dev/null +++ b/Makefile @@ -0,0 +1,29 @@ +# You can set these variables from the command line. +CPYTHON_PATH = ../cpython +PYTHON = python3 +PACKAGE_ABS_PATH = $(shell pwd)/$(shell find dist/python-docs-theme-*.tar.gz) + + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " venv to create a venv with necessary tools at $(CPYTHON_PATH)/Doc/venv" + @echo " html to make standalone CPython HTML files" + @echo " htmlview to open the index page built by the html target in your browser" + +.PHONY: venv +venv: + $(PYTHON) -m pip install build + $(PYTHON) -m build + cd $(CPYTHON_PATH)/Doc \ + && make venv \ + && ./venv/bin/pip install $(PACKAGE_ABS_PATH) + +.PHONY: html +html: venv + cd $(CPYTHON_PATH)/Doc && \ + make html + +.PHONY: htmlview +htmlview: html + $(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('$(CPYTHON_PATH)/Doc/build/html/index.html'))" diff --git a/README.md b/README.md new file mode 100644 index 00000000..fedd7f76 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# Python Docs Sphinx Theme + +This is the theme for the Python documentation. +It requires Python 3.12 or newer and Sphinx 7.3 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 +years. That's fine, and you're welcome to do so for other Python community +projects if you so choose, but please keep in mind that in doing so you're also +choosing to accept some of the responsibility for maintaining that collective +trust. + +To use the theme, install it into your docs build environment via `pip` +(preferably in a virtual environment). + + +## Configuration options + +To use this theme, add the following to `conf.py`: + +- `html_theme = 'python_docs_theme'` + +- `html_sidebars`, defaults taken from https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars + +## Preview + +See a demo of the CPython docs using this theme: + +- https://python-docs-theme-previews.readthedocs.io + +The kitchen sink is a showcase of every Sphinx feature: + +- https://sphinx-themes.org/sample-sites/python-docs-theme/kitchen-sink/ diff --git a/README.rst b/README.rst deleted file mode 100644 index 3f2e8443..00000000 --- a/README.rst +++ /dev/null @@ -1,24 +0,0 @@ -Python Docs Sphinx Theme -========================= - -This is the theme for the Python documentation. - -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 -years. That's fine, and you're welcome to do so for other Python community -projects if you so choose, but please keep in mind that in doing so you're also -choosing to accept some of the responsibility for maintaining that collective -trust. - -To use the theme, install it into your docs build environment via ``pip`` -(preferably in a virtual environment). - - -Configuration options ---------------------- - -To use this theme, add the following to ``conf.py``: - -- ``html_theme = 'python_docs_theme'`` - -- ``html_sidebars``, defaults taken from http://www.sphinx-doc.org/en/stable/config.html#confval-html_sidebars diff --git a/babel_runner.py b/babel_runner.py new file mode 100755 index 00000000..0785ae2f --- /dev/null +++ b/babel_runner.py @@ -0,0 +1,128 @@ +#!/usr/bin/venv python3 +"""Script for handling translations with Babel""" +from __future__ import annotations + +import argparse +import ast +import subprocess +import tomllib +from pathlib import Path + +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" +COPYRIGHT_HOLDER = "Python Software Foundation" +LOCALES_DIR = "locales" +POT_FILE = Path(LOCALES_DIR, f"{DOMAIN}.pot") +SOURCE_DIR = "python_docs_theme" +MAPPING_FILE = ".babel.cfg" + + +def get_project_info() -> dict: + """Retrieve project's info to populate the message catalog template""" + 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: + """Extract messages from all source files into message catalog template""" + Path(PROJECT_DIR, LOCALES_DIR).mkdir(parents=True, exist_ok=True) + project_data = get_project_info() + subprocess.run( + [ + "pybabel", + "extract", + "-F", + MAPPING_FILE, + "--copyright-holder", + COPYRIGHT_HOLDER, + "--project", + project_data["name"], + "--version", + project_data["version"], + "--msgid-bugs-address", + project_data["urls"]["Issue tracker"], + "-o", + POT_FILE, + SOURCE_DIR, + ], + cwd=PROJECT_DIR, + check=True, + ) + + +def init_locale(locale: str) -> None: + """Initialize a new locale based on existing message catalog template""" + pofile = PROJECT_DIR / LOCALES_DIR / locale / "LC_MESSAGES" / f"{DOMAIN}.po" + if pofile.exists(): + print(f"There is already a message catalog for locale {locale}, skipping.") + return + cmd = ["pybabel", "init", "-i", POT_FILE, "-d", LOCALES_DIR, "-l", locale] + subprocess.run(cmd, cwd=PROJECT_DIR, check=True) + + +def update_catalogs(locale: str) -> None: + """Update translations from existing message catalogs""" + cmd = ["pybabel", "update", "-i", POT_FILE, "-d", LOCALES_DIR] + if locale: + cmd.extend(["-l", locale]) + subprocess.run(cmd, cwd=PROJECT_DIR, check=True) + + +def compile_catalogs(locale: str) -> None: + """Compile existing message catalogs""" + cmd = ["pybabel", "compile", "-d", LOCALES_DIR] + if locale: + cmd.extend(["-l", locale]) + subprocess.run(cmd, cwd=PROJECT_DIR, check=True) + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "command", + choices=["extract", "init", "update", "compile"], + help="command to be executed", + ) + parser.add_argument( + "-l", + "--locale", + default="", + help="language code (needed for init, optional for update and compile)", + ) + + args = parser.parse_args() + locale = args.locale + + if args.command == "extract": + extract_messages() + elif args.command == "init": + if not locale: + parser.error("init requires passing the --locale option") + init_locale(locale) + elif args.command == "update": + update_catalogs(locale) + elif args.command == "compile": + compile_catalogs(locale) + + +if __name__ == "__main__": + main() diff --git a/code_of_conduct.rst b/code_of_conduct.rst deleted file mode 100644 index 28de97ce..00000000 --- a/code_of_conduct.rst +++ /dev/null @@ -1,14 +0,0 @@ -Code of Conduct -=============== - -Please note that all interactions on -`Python Software Foundation `__-supported -infrastructure is `covered -`__ -by the `PSF Code of Conduct `__, -which includes all infrastructure used in the development of Python itself -(e.g. mailing lists, issue trackers, GitHub, etc.). - -In general this means everyone is expected to be open, considerate, and -respectful of others no matter what their position is within the project. - diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..a614351d --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,73 @@ +[build-system] +build-backend = "flit_core.buildapi" +requires = [ + "flit-core>=3.7", +] + +[project] +name = "python-docs-theme" +description = "The Sphinx theme for the CPython docs and related projects" +readme = "README.md" +license = "PSF-2.0" +license-files = [ "LICENSE" ] +authors = [ { name = "PyPA", email = "distutils-sig@python.org" } ] +requires-python = ">=3.12" +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Framework :: Sphinx :: Theme", + "Intended Audience :: Developers", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + "Topic :: Documentation", + "Topic :: Software Development :: Documentation", +] +dynamic = [ "version" ] + +dependencies = [ + "sphinx>=7.3", +] + +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/" +urls."Issue tracker" = "https://github.com/python/python-docs-theme/issues" +entry-points."sphinx.html_themes".python_docs_theme = "python_docs_theme" + +[tool.flit.module] +name = "python_docs_theme" + +[tool.flit.sdist] +include = [ "python_docs_theme/" ] + +[tool.ruff] +fix = true + +lint.select = [ + "C4", # flake8-comprehensions + "E", # pycodestyle errors + "F", # pyflakes errors + "I", # isort + "ISC", # flake8-implicit-str-concat + "LOG", # flake8-logging + "PGH", # pygrep-hooks + "PYI", # flake8-pyi + "RUF022", # unsorted-dunder-all + "RUF100", # unused noqa (yesqa) + "UP", # pyupgrade + "W", # pycodestyle warnings + "YTT", # flake8-2020 +] +lint.ignore = [ + "E203", # Whitespace before ':' + "E221", # Multiple spaces before operator + "E226", # Missing whitespace around arithmetic operator + "E241", # Multiple spaces after ',' +] +lint.isort.required-imports = [ "from __future__ import annotations" ] + +[tool.pyproject-fmt] +max_supported_python = "3.14" diff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.py index 407d62a8..75459e1a 100644 --- a/python_docs_theme/__init__.py +++ b/python_docs_theme/__init__.py @@ -1,12 +1,24 @@ -import os +from __future__ import annotations +from pathlib import Path -def setup(app): - current_dir = os.path.abspath(os.path.dirname(__file__)) - app.add_html_theme( - 'python_docs_theme', current_dir) +TYPE_CHECKING = False +if TYPE_CHECKING: + from sphinx.application import Sphinx + from sphinx.util.typing import ExtensionMetadata + +__version__ = "2025.4.1" + +THEME_PATH = Path(__file__).resolve().parent + + +def setup(app: Sphinx) -> ExtensionMetadata: + app.require_sphinx("7.3") + + app.add_html_theme("python_docs_theme", str(THEME_PATH)) return { - 'parallel_read_safe': True, - 'parallel_write_safe': True, + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, } diff --git a/python_docs_theme/footerdonate.html b/python_docs_theme/footerdonate.html index 2aef2ac2..010014d6 100644 --- a/python_docs_theme/footerdonate.html +++ b/python_docs_theme/footerdonate.html @@ -1,3 +1,3 @@ {% trans %}The Python Software Foundation is a non-profit corporation.{% endtrans %} {% trans %}Please donate.{% endtrans %} -
+
diff --git a/python_docs_theme/layout.html b/python_docs_theme/layout.html index c4a48fa6..a74517c9 100644 --- a/python_docs_theme/layout.html +++ b/python_docs_theme/layout.html @@ -1,65 +1,171 @@ {% extends "classic/layout.html" %} -{% block rootrellink %} -
    • -
  • {{theme_root_name}}{{ reldelim1 }}
    • - {% if theme_root_include_title %} - {{ shorttitle }}{{ reldelim1 }} - {% endif %} -{% endblock %} +{%- macro relbar() %} +{# modified from sphinx/themes/basic/layout.html #} + +{%- endmacro %} {%- macro searchbox() %} {# modified from sphinx/themes/basic/searchbox.html #} {%- if builder != "htmlhelp" %} -