diff --git a/.babel.cfg b/.babel.cfg index 692580d..cc4c9de 100644 --- a/.babel.cfg +++ b/.babel.cfg @@ -1 +1,3 @@ +[javascript: **.js] + [jinja2: **.html] diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 823b67f..a7a064a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -12,12 +12,12 @@ jobs: strategy: fail-fast: false matrix: - branch: ["origin/main", "3.13", "3.12", "3.11", "3.10"] + branch: ["3.14", "3.13", "3.12"] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: - python-version: 3 + python-version: ${{ matrix.branch }} allow-prereleases: true cache: pip - name: Clone docsbuild scripts @@ -37,8 +37,9 @@ jobs: --group "$(id -g)" --skip-cache-invalidation --theme "$(pwd)" - --language en - --branch ${{ matrix.branch }} + --languages en + --branches ${{ matrix.branch }} + ${{ matrix.branch == '3.14' && '--select-output no-html' || '' }} - name: Show logs if: failure() run: | @@ -56,7 +57,7 @@ jobs: matrix: os: ["ubuntu-latest", "windows-latest"] # Test minimum supported and latest stable from 3.x series - python-version: ["3.10", "3"] + python-version: ["3.12", "3"] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f964364..9a7e83b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -36,7 +36,6 @@ repos: rev: v2.5.0 hooks: - id: pyproject-fmt - args: [--max-supported-python=3.13] - repo: https://github.com/abravalheri/validate-pyproject rev: v0.23 diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 74b09ca..fb43a9f 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -1,6 +1,23 @@ 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 `_ --------------------------------------------------------------------------- diff --git a/README.md b/README.md index 133daa0..fedd7f7 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Python Docs Sphinx Theme This is the theme for the Python documentation. -It requires Python 3.10 or newer and Sphinx 7.3 or newer. +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 diff --git a/babel_runner.py b/babel_runner.py index af752fc..9e42138 100755 --- a/babel_runner.py +++ b/babel_runner.py @@ -5,18 +5,9 @@ import argparse import ast import subprocess +import tomllib from pathlib import Path -try: - import tomllib -except ImportError: - try: - import tomli as tomllib - except ImportError as ie: - raise ImportError( - "tomli or tomllib is required to parse pyproject.toml" - ) from ie - PROJECT_DIR = Path(__file__).resolve().parent PYPROJECT_TOML = PROJECT_DIR / "pyproject.toml" INIT_PY = PROJECT_DIR / "python_docs_theme" / "__init__.py" diff --git a/pyproject.toml b/pyproject.toml index e03e2be..a614351 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,21 +8,20 @@ requires = [ name = "python-docs-theme" description = "The Sphinx theme for the CPython docs and related projects" readme = "README.md" -license.file = "LICENSE" +license = "PSF-2.0" +license-files = [ "LICENSE" ] authors = [ { name = "PyPA", email = "distutils-sig@python.org" } ] -requires-python = ">=3.10" +requires-python = ">=3.12" classifiers = [ "Development Status :: 5 - Production/Stable", "Framework :: Sphinx :: Theme", "Intended Audience :: Developers", - "License :: OSI Approved :: Python Software Foundation License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Topic :: Documentation", "Topic :: Software Development :: Documentation", ] @@ -69,3 +68,6 @@ lint.ignore = [ "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 c5b5fe7..aab0aaf 100644 --- a/python_docs_theme/__init__.py +++ b/python_docs_theme/__init__.py @@ -2,20 +2,32 @@ from pathlib import Path +import gettext + TYPE_CHECKING = False if TYPE_CHECKING: from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata -__version__ = "2025.2" +__version__ = "2025.4.1" THEME_PATH = Path(__file__).resolve().parent +def _setup_translations(app): + language = app.config.language or 'en' + try: + translation = gettext.translation(domain="messages", localedir=str(THEME_PATH / "locales"), languages=[language]) + app.builder.templates.environment.install_gettext_translations(translation, newstyle=True) + except FileNotFoundError: + app.builder.templates.environment.install_gettext(lambda x: x, newstyle=True) + + def setup(app: Sphinx) -> ExtensionMetadata: app.require_sphinx("7.3") app.add_html_theme("python_docs_theme", str(THEME_PATH)) + app.connect("builder-inited", _setup_translations) return { "version": __version__, diff --git a/python_docs_theme/footerdonate.html b/python_docs_theme/footerdonate.html index 2aef2ac..010014d 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 9762b06..a74517c 100644 --- a/python_docs_theme/layout.html +++ b/python_docs_theme/layout.html @@ -14,7 +14,7 @@

{{ _('Navigation') }}

{%- endfor %} {%- block rootrellink %} -
  • {{ theme_root_icon_alt_text }}
    • +
  • {{ theme_root_icon_alt_text }}
  • {{theme_root_name}}{{ reldelim1 }}
  • @@ -48,8 +48,8 @@

    {{ _('Navigation') }}

    {%- if builder != "htmlhelp" %} {%- endif %} @@ -71,7 +71,7 @@

    {{ _('Navigation') }}

    {%- block extrahead -%} - + {%- if builder != "htmlhelp" %} {%- if not embedded %} @@ -93,14 +93,14 @@

    {{ _('Navigation') }}

    {%- if builder != 'htmlhelp' %}
    + aria-pressed="false" aria-expanded="false" role="button" aria-label="{{ _('Menu')}}">
    diff --git a/python_docs_theme/locales/pl_PL/LC_MESSAGES/messages.po b/python_docs_theme/locales/pl_PL/LC_MESSAGES/messages.po new file mode 100644 index 0000000..6cefefa --- /dev/null +++ b/python_docs_theme/locales/pl_PL/LC_MESSAGES/messages.po @@ -0,0 +1,123 @@ +# Polish (Poland) translations for python-docs-theme. +# Copyright (C) 2025 Python Software Foundation +# This file is distributed under the same license as the python-docs-theme +# project. +# FIRST AUTHOR , 2025. +# +msgid "" +msgstr "" +"Project-Id-Version: python-docs-theme 2025.4.1\n" +"Report-Msgid-Bugs-To: https://github.com/python/python-docs-theme/" +"issues\n" +"POT-Creation-Date: 2025-05-21 17:34+0100\n" +"PO-Revision-Date: 2025-05-21 17:39+0100\n" +"Last-Translator: Stan Ulbrych \n" +"Language-Team: pl_PL \n" +"Language: pl_PL\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && " +"(n%100<10 || n%100>=20) ? 1 : 2);\n" +"Generated-By: Babel 2.16.0\n" +"X-Generator: Poedit 3.6\n" + +#: python_docs_theme/footerdonate.html:1 +msgid "The Python Software Foundation is a non-profit corporation." +msgstr "Python Software Foundation jest organizacją non-profit." + +#: python_docs_theme/footerdonate.html:2 +msgid "Please donate." +msgstr "" + +#: python_docs_theme/layout.html:6 +msgid "Navigation" +msgstr "Navigation" + +#: python_docs_theme/layout.html:51 python_docs_theme/layout.html:111 +msgid "Quick search" +msgstr "Szybkie wyszukiwanie" + +#: python_docs_theme/layout.html:52 python_docs_theme/layout.html:112 +msgid "Go" +msgstr "Idź" + +#: python_docs_theme/layout.html:60 +msgid "Theme" +msgstr "" + +#: python_docs_theme/layout.html:62 +msgid "Auto" +msgstr "Auto" + +#: python_docs_theme/layout.html:63 +msgid "Light" +msgstr "Jasny" + +#: python_docs_theme/layout.html:64 +msgid "Dark" +msgstr "Ciemny" + +#: python_docs_theme/layout.html:96 +msgid "Menu" +msgstr "Menu" + +#: python_docs_theme/layout.html:142 +msgid "Copyright" +msgstr "" + +#: python_docs_theme/layout.html:147 +msgid "" +"This page is licensed under the Python Software Foundation License " +"Version 2." +msgstr "" + +#: python_docs_theme/layout.html:149 +msgid "" +"Examples, recipes, and other code in the documentation are additionally " +"licensed under the Zero Clause BSD License." +msgstr "" + +#: python_docs_theme/layout.html:152 +#, python-format +msgid "" +"See History and License for more " +"information." +msgstr "" + +#: python_docs_theme/layout.html:155 +#, python-format +msgid "Hosted on %(hosted_on)s." +msgstr "" + +#: python_docs_theme/layout.html:163 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "" + +#: python_docs_theme/layout.html:166 +#, python-format +msgid "Found a bug?" +msgstr "Znalazłeś błąd?" + +#: python_docs_theme/layout.html:170 +#, python-format +msgid "" +"Created using Sphinx " +"%(sphinx_version)s." +msgstr "" +"Stworzone przy użyciu Sphinx %(sphinx_version)s." + +#: python_docs_theme/static/copybutton.js:30 +#: python_docs_theme/static/copybutton.js:55 +msgid "Copy" +msgstr "Kopiuj" + +#: python_docs_theme/static/copybutton.js:31 +msgid "Copy to clipboard" +msgstr "Skopiuj do schowka" + +#: python_docs_theme/static/copybutton.js:53 +msgid "Copied!" +msgstr "Skopiowano!" diff --git a/python_docs_theme/static/copybutton.js b/python_docs_theme/static/copybutton.js index 7367c4a..de071f4 100644 --- a/python_docs_theme/static/copybutton.js +++ b/python_docs_theme/static/copybutton.js @@ -1,65 +1,59 @@ -// ``function*`` denotes a generator in JavaScript, see -// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function* -function* getHideableCopyButtonElements(rootElement) { - // yield all elements with the "go" (Generic.Output), - // "gp" (Generic.Prompt), or "gt" (Generic.Traceback) CSS class - for (const el of rootElement.querySelectorAll('.go, .gp, .gt')) { - yield el - } - // tracebacks (.gt) contain bare text elements that need to be - // wrapped in a span to hide or show the element - for (let el of rootElement.querySelectorAll('.gt')) { - while ((el = el.nextSibling) && el.nodeType !== Node.DOCUMENT_NODE) { - // stop wrapping text nodes when we hit the next output or - // prompt element - if (el.nodeType === Node.ELEMENT_NODE && el.matches(".gp, .go")) { - break - } - // if the node is a text node with content, wrap it in a - // span element so that we can control visibility - if (el.nodeType === Node.TEXT_NODE && el.textContent.trim()) { - const wrapper = document.createElement("span") - el.after(wrapper) - wrapper.appendChild(el) - el = wrapper - } - yield el +// Extract copyable text from the code block ignoring the +// prompts and output. +function getCopyableText(rootElement) { + rootElement = rootElement.cloneNode(true) + // tracebacks (.gt) contain bare text elements that + // need to be removed + const tracebacks = rootElement.querySelectorAll(".gt") + for (const el of tracebacks) { + while ( + el.nextSibling && + (el.nextSibling.nodeType !== Node.ELEMENT_NODE || + !el.nextSibling.matches(".gp, .go")) + ) { + el.nextSibling.remove() } } + // Remove all elements with the "go" (Generic.Output), + // "gp" (Generic.Prompt), or "gt" (Generic.Traceback) CSS class + const elements = rootElement.querySelectorAll(".gp, .go, .gt") + for (const el of elements) { + el.remove() + } + return rootElement.innerText.trim() } - const loadCopyButton = () => { - /* Add a [>>>] button in the top-right corner of code samples to hide - * the >>> and ... prompts and the output and thus make the code - * copyable. */ - const hide_text = "Hide the prompts and output" - const show_text = "Show the prompts and output" - - const button = document.createElement("span") + const button = document.createElement("button") button.classList.add("copybutton") - button.innerText = ">>>" - button.title = hide_text - button.dataset.hidden = "false" - const buttonClick = event => { + button.type = "button" + button.innerText = _("Copy") + button.title = _("Copy to clipboard") + + const makeOnButtonClick = () => { + let timeout = null // define the behavior of the button when it's clicked - event.preventDefault() - const buttonEl = event.currentTarget - const codeEl = buttonEl.nextElementSibling - if (buttonEl.dataset.hidden === "false") { - // hide the code output - for (const el of getHideableCopyButtonElements(codeEl)) { - el.hidden = true + return async event => { + // check if the clipboard is available + if (!navigator.clipboard || !navigator.clipboard.writeText) { + return; } - buttonEl.title = show_text - buttonEl.dataset.hidden = "true" - } else { - // show the code output - for (const el of getHideableCopyButtonElements(codeEl)) { - el.hidden = false + + clearTimeout(timeout) + const buttonEl = event.currentTarget + const codeEl = buttonEl.nextElementSibling + + try { + await navigator.clipboard.writeText(getCopyableText(codeEl)) + } catch (e) { + console.error(e.message) + return } - buttonEl.title = hide_text - buttonEl.dataset.hidden = "false" + + buttonEl.innerText = _("Copied!") + timeout = setTimeout(() => { + buttonEl.innerText = _("Copy") + }, 1500) } } @@ -78,10 +72,8 @@ const loadCopyButton = () => { // if we find a console prompt (.gp), prepend the (deeply cloned) button const clonedButton = button.cloneNode(true) // the onclick attribute is not cloned, set it on the new element - clonedButton.onclick = buttonClick - if (el.querySelector(".gp") !== null) { - el.prepend(clonedButton) - } + clonedButton.onclick = makeOnButtonClick() + el.prepend(clonedButton) }) } diff --git a/python_docs_theme/static/pydoctheme.css b/python_docs_theme/static/pydoctheme.css index da47d3e..6d50092 100644 --- a/python_docs_theme/static/pydoctheme.css +++ b/python_docs_theme/static/pydoctheme.css @@ -328,6 +328,10 @@ tt, code, pre { font-size: 96.5%; } +div.body pre { + line-height: 120%; +} + div.body tt, div.body code { border-radius: 3px; @@ -438,17 +442,23 @@ div.genindex-jumpbox a { top: 0; right: 0; font-family: Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace; - padding-left: 0.2em; - padding-right: 0.2em; + font-size: 80%; + padding-left: .5em; + padding-right: .5em; + height: 100%; + max-height: min(100%, 2.4em); border-radius: 0 3px 0 0; - color: #ac9; /* follows div.body pre */ - border-color: #ac9; /* follows div.body pre */ - border-style: solid; /* follows div.body pre */ - border-width: 1px; /* follows div.body pre */ + color: #000; + background-color: #fff; + border: 1px solid #ac9; /* follows div.body pre */ +} + +.copybutton:hover { + background-color: #eee; } -.copybutton[data-hidden='true'] { - text-decoration: line-through; +.copybutton:active { + background-color: #ddd; } @media (max-width: 1023px) { diff --git a/python_docs_theme/static/pydoctheme_dark.css b/python_docs_theme/static/pydoctheme_dark.css index 4509960..582e4dd 100644 --- a/python_docs_theme/static/pydoctheme_dark.css +++ b/python_docs_theme/static/pydoctheme_dark.css @@ -176,3 +176,16 @@ img.invert-in-dark-mode { --versionchanged: var(--middle-color); --deprecated: var(--bad-color); } + +.copybutton { + color: #ac9; /* follows div.body pre */ + background-color: #222222; /* follows body */ +} + +.copybutton:hover { + background-color: #434343; +} + +.copybutton:active { + background-color: #656565; +} diff --git a/requirements.txt b/requirements.txt index ad829d4..bb631b5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,3 @@ # for babel_runner.py -setuptools Babel Jinja2 -tomli; python_version < "3.11"