Feb 13, 2025 · Feb 2, 2025 · Feb 2, 2025 · Feb 2, 2025 · Feb 2, 2025 · Feb 2, 2025
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
      matrix:
        os: ["ubuntu-latest", "windows-latest"]
        # Test minimum supported and latest stable from 3.x series
        python-version: ["3.9", "3"]
        python-version: ["3.10", "3"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
diff --git a/README.md b/README.md
 # Python Docs Sphinx Theme

 This is the theme for the Python documentation.
 It requires Python 3.9 or newer and Sphinx3.4 or newer.
 It requires Python 3.10 or newer and Sphinx7.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/pyproject.toml b/pyproject.toml
 readme = "README.md"
 license.file = "LICENSE"
 authors = [ { name = "PyPA", email = "distutils-sig@python.org" } ]
 requires-python = ">=3.9"
 requires-python = ">=3.10"
 classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Framework :: Sphinx :: Theme",
  "Operating System :: OS Independent",
  "Programming Language :: Python",
  "Programming Language :: Python :: 3 :: Only",
  "Programming Language :: Python :: 3.9",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
 dynamic = [ "version" ]

 dependencies = [
  "sphinx>=3.4",
  "sphinx>=7.3",
 ]

 urls.Code = "https://github.com/python/python-docs-theme"
diff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.py
 from __future__ import annotations

 import hashlib
 from functools import cache
 from pathlib import Path

 import sphinx.application
 from sphinx.builders.html import StandaloneHTMLBuilder

 TYPE_CHECKING = False
 if TYPE_CHECKING:
    from typing import Any

    from sphinx.application import Sphinx
    from sphinx.util.typing import ExtensionMetadata

 THEME_PATH = Path(__file__).resolve().parent


 @cache
 def _asset_hash(path: str) -> str:
    """Append a `?digest=` to an url based on the file content."""
    full_path = THEME_PATH / path.replace("_static/", "static/")
    digest = hashlib.sha1(full_path.read_bytes()).hexdigest()

    return f"{path}?digest={digest}"


 def _add_asset_hashes(static: list[str], add_digest_to: list[str]) -> None:
    for asset in add_digest_to:
        index = static.index(asset)
        static[index].filename = _asset_hash(asset)  # type: ignore[attr-defined]


 def _html_page_context(
    app: sphinx.application.Sphinx,
    pagename: str,
    templatename: str,
    context: dict[str, Any],
    doctree: Any,
 ) -> None:
    if app.config.html_theme != "python_docs_theme":
        return

    assert isinstance(app.builder, StandaloneHTMLBuilder)

    if (4,) <= sphinx.version_info < (7, 1) and "css_files" in context:
        if "_static/pydoctheme.css" not in context["css_files"]:
            raise ValueError(
                "This documentation is not using `pydoctheme.css` as the stylesheet. "
                "If you have set `html_style` in your conf.py file, remove it."
            )

        _add_asset_hashes(
            context["css_files"],
            ["_static/pydoctheme.css"],
        )


 def setup(app: Sphinx) -> ExtensionMetadata:
    app.require_sphinx("3.4")
    app.require_sphinx("7.3")

    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,
diff --git a/python_docs_theme/static/pydoctheme.css b/python_docs_theme/static/pydoctheme.css
 @import url('classic.css');

 /* Common colours */
 :root {
    --good-color: rgb(41 100 51);
    display: flex;
    justify-content: center;
    align-items: center;
    /* Sphinx 4.x and earlier compat */
    height: 100%;
    background-color: #CCCCCC;
    margin-left: 0;
    color: #444444;
    font-size: 1.2em;
    cursor: pointer;
    padding-top: 1px;
    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;
diff --git a/python_docs_theme/static/sidebar.js_t b/python_docs_theme/static/sidebar.js_t
diff --git a/python_docs_theme/theme.conf b/python_docs_theme/theme.conf
diff --git a/python_docs_theme/theme.toml b/python_docs_theme/theme.toml
 [theme]
 inherit = "default"
 stylesheets = [
    "classic.css",
    "pydoctheme.css",
 ]
 pygments_style = { default = "default", dark = "monokai" }

 [options]
 bodyfont = "-apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Cantarell, Ubuntu, roboto, noto, arial, sans-serif"
 headfont = "-apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Cantarell, Ubuntu, roboto, noto, arial, sans-serif"
 footerbgcolor = "white"
 footertextcolor = "#555555"
 relbarbgcolor = "white"
 relbartextcolor = "#666666"
 relbarlinkcolor = "#444444"
 sidebarbgcolor = "white"
 sidebartextcolor = "#444444"
 sidebarlinkcolor = "#444444"
 sidebarbtncolor = "#cccccc"
 bgcolor = "white"
 textcolor = "#222222"
 linkcolor = "#0090c0"
 visitedlinkcolor = "#00608f"
 headtextcolor = "#1a1a1a"
 headbgcolor = "white"
 headlinkcolor = "#aaaaaa"
 codebgcolor = "#eeffcc"
 codetextcolor = "#333333"

 hosted_on = ""
 issues_url = ""
 license_url = ""
 root_name = "Python"
 root_url = "https://www.python.org/"
 root_icon = "py.svg"
 root_icon_alt_text = "Python logo"
 root_include_title = "True"
 copyright_url = ""
Original file line number	Diff line number	Diff line change
Expand Up		@@ -56,7 +56,7 @@ jobs:
		matrix:
		os: ["ubuntu-latest", "windows-latest"]
		# Test minimum supported and latest stable from 3.x series
		python-version: ["3.9", "3"]
		python-version: ["3.10", "3"]
		steps:
		- uses: actions/checkout@v4
		- uses: actions/setup-python@v5
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,7 +1,7 @@
		# Python Docs Sphinx Theme

		This is the theme for the Python documentation.
		It requires Python 3.9 or newer and Sphinx3.4 or newer.
		It requires Python 3.10 or newer and Sphinx7.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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -10,7 +10,7 @@ description = "The Sphinx theme for the CPython docs and related projects"
		readme = "README.md"
		license.file = "LICENSE"
		authors = [ { name = "PyPA", email = "distutils-sig@python.org" } ]
		requires-python = ">=3.9"
		requires-python = ">=3.10"
		classifiers = [
		"Development Status :: 5 - Production/Stable",
		"Framework :: Sphinx :: Theme",
Expand All		@@ -19,7 +19,6 @@ classifiers = [
		"Operating System :: OS Independent",
		"Programming Language :: Python",
		"Programming Language :: Python :: 3 :: Only",
		"Programming Language :: Python :: 3.9",
		"Programming Language :: Python :: 3.10",
		"Programming Language :: Python :: 3.11",
		"Programming Language :: Python :: 3.12",
Expand All		@@ -30,7 +29,7 @@ classifiers = [
		dynamic = [ "version" ]

		dependencies = [
		"sphinx>=3.4",
		"sphinx>=7.3",
		]

		urls.Code = "https://github.com/python/python-docs-theme"
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,16 +1,9 @@
		from __future__ import annotations

		import hashlib
		from functools import cache
		from pathlib import Path

		import sphinx.application
		from sphinx.builders.html import StandaloneHTMLBuilder

		TYPE_CHECKING = False
		if TYPE_CHECKING:
		from typing import Any

		from sphinx.application import Sphinx
		from sphinx.util.typing import ExtensionMetadata

Expand All		@@ -19,53 +12,11 @@
		THEME_PATH = Path(__file__).resolve().parent


		@cache
		def _asset_hash(path: str) -> str:
		"""Append a `?digest=` to an url based on the file content."""
		full_path = THEME_PATH / path.replace("_static/", "static/")
		digest = hashlib.sha1(full_path.read_bytes()).hexdigest()

		return f"{path}?digest={digest}"


		def _add_asset_hashes(static: list[str], add_digest_to: list[str]) -> None:
		for asset in add_digest_to:
		index = static.index(asset)
		static[index].filename = _asset_hash(asset) # type: ignore[attr-defined]


		def _html_page_context(
		app: sphinx.application.Sphinx,
		pagename: str,
		templatename: str,
		context: dict[str, Any],
		doctree: Any,
		) -> None:
		if app.config.html_theme != "python_docs_theme":
		return

		assert isinstance(app.builder, StandaloneHTMLBuilder)

		if (4,) <= sphinx.version_info < (7, 1) and "css_files" in context:
AA-Turner marked this conversation as resolved. Show resolvedHide resolved
		if "_static/pydoctheme.css" not in context["css_files"]:
		raise ValueError(
		"This documentation is not using `pydoctheme.css` as the stylesheet. "
		"If you have set `html_style` in your conf.py file, remove it."
		)

		_add_asset_hashes(
		context["css_files"],
		["_static/pydoctheme.css"],
		)


		def setup(app: Sphinx) -> ExtensionMetadata:
		app.require_sphinx("3.4")
		app.require_sphinx("7.3")

		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,
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,5 +1,3 @@
		@import url('classic.css');

		/* Common colours */
		:root {
		--good-color: rgb(41 100 51);
Expand DownExpand Up		@@ -200,16 +198,6 @@ div.sphinxsidebar input[type='text'] {
		display: flex;
		justify-content: center;
		align-items: center;
		/* Sphinx 4.x and earlier compat */
		height: 100%;
		background-color: #CCCCCC;
		margin-left: 0;
		color: #444444;
		font-size: 1.2em;
		cursor: pointer;
		padding-top: 1px;
		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;
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,39 @@
		[theme]
		inherit = "default"
		stylesheets = [
		"classic.css",
		"pydoctheme.css",
		]
		pygments_style = { default = "default", dark = "monokai" }

		[options]
		bodyfont = "-apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Cantarell, Ubuntu, roboto, noto, arial, sans-serif"
		headfont = "-apple-system, BlinkMacSystemFont, avenir next, avenir, segoe ui, helvetica neue, helvetica, Cantarell, Ubuntu, roboto, noto, arial, sans-serif"
		footerbgcolor = "white"
		footertextcolor = "#555555"
		relbarbgcolor = "white"
		relbartextcolor = "#666666"
		relbarlinkcolor = "#444444"
		sidebarbgcolor = "white"
		sidebartextcolor = "#444444"
		sidebarlinkcolor = "#444444"
		sidebarbtncolor = "#cccccc"
		bgcolor = "white"
		textcolor = "#222222"
		linkcolor = "#0090c0"
		visitedlinkcolor = "#00608f"
		headtextcolor = "#1a1a1a"
		headbgcolor = "white"
		headlinkcolor = "#aaaaaa"
		codebgcolor = "#eeffcc"
		codetextcolor = "#333333"

		hosted_on = ""
		issues_url = ""
		license_url = ""
		root_name = "Python"
		root_url = "https://www.python.org/"
		root_icon = "py.svg"
		root_icon_alt_text = "Python logo"
		root_include_title = "True"
		copyright_url = ""