diff --git a/.flake8 b/.flake8 new file mode 100644 index 0000000..2bcd70e --- /dev/null +++ b/.flake8 @@ -0,0 +1,2 @@ +[flake8] +max-line-length = 88 diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..8509763 --- /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@v4 + with: + python-version: "3.x" + - uses: pre-commit/action@v3.0.0 diff --git a/.github/workflows/pypi-package.yml b/.github/workflows/pypi-package.yml index 2b8f8aa..355a35f 100644 --- a/.github/workflows/pypi-package.yml +++ b/.github/workflows/pypi-package.yml @@ -18,7 +18,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: hynek/build-and-inspect-python-package@v1 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index fa5ed35..9407ac7 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -1,22 +1,25 @@ name: Tests -on: - push: - pull_request: - workflow_dispatch: +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: [origin/main, 3.12, 3.11, '3.10', 3.9, 3.8] + branch: ["origin/main", "3.12", "3.11", "3.10", "3.9", "3.8"] steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: actions/setup-python@v4 with: python-version: 3 + allow-prereleases: true + cache: pip - name: Clone docsbuild scripts run: | git clone https://github.com/python/docsbuild-scripts/ @@ -26,16 +29,20 @@ jobs: 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) - --language en + 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) + --language en --branch ${{ matrix.branch }} + - name: Show logs + if: failure() + run: | + cat ./logs/docsbuild.log - name: Upload uses: actions/upload-artifact@v3 with: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..008784c --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,50 @@ +repos: + - repo: https://github.com/asottile/pyupgrade + rev: v3.15.0 + hooks: + - id: pyupgrade + args: [--py38-plus] + + - repo: https://github.com/psf/black-pre-commit-mirror + rev: 23.9.1 + hooks: + - id: black + + - repo: https://github.com/PyCQA/isort + rev: 5.12.0 + hooks: + - id: isort + args: [--add-import=from __future__ import annotations] + + - repo: https://github.com/PyCQA/flake8 + rev: 6.1.0 + hooks: + - id: flake8 + additional_dependencies: + [flake8-2020, flake8-implicit-str-concat, flake8-logging] + + - repo: https://github.com/pre-commit/pygrep-hooks + rev: v1.10.0 + hooks: + - id: python-check-blanket-noqa + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: check-case-conflict + - id: check-executables-have-shebangs + - id: check-merge-conflict + - id: check-json + - id: check-toml + - id: check-yaml + - id: debug-statements + - id: end-of-file-fixer + - id: trailing-whitespace + + - repo: https://github.com/abravalheri/validate-pyproject + rev: v0.14 + hooks: + - id: validate-pyproject + +ci: + autoupdate_schedule: quarterly diff --git a/CHANGELOG.rst b/CHANGELOG.rst index ed7ca86..f44760d 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -2,6 +2,18 @@ Changelog ========= +`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 `_ ---------------------------------------------------------------------------- diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0b2fbd6..2533e96 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,18 +1,21 @@ How to release -------------- -- Update CHANGELOG.rst -- bump version (YYYY.MM) in pyproject.toml -- commit -- push to check one last time if the tests pass github side. -- tag it (YYYY.MM). -- build (``python -m build``) -- Test it (in :file:`cpython/Doc` run - ``./venv/bin/pip install ../../python-docs-theme/dist/python-docs-theme-2021.8.tar.gz`` - then build the doc using ``make html``). -- upload it: ``twine upload dist/*``. -- push the tag (``git push --tags``) - +- Update ``CHANGELOG.rst`` +- Bump version (YYYY.MM) in ``pyproject.toml`` +- 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 -------------- diff --git a/README.rst b/README.rst index 3f2e844..0a8db3f 100644 --- a/README.rst +++ b/README.rst @@ -10,7 +10,7 @@ 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`` +To use the theme, install it into your docs build environment via ``pip`` (preferably in a virtual environment). diff --git a/code_of_conduct.rst b/code_of_conduct.rst index 28de97c..4bc6630 100644 --- a/code_of_conduct.rst +++ b/code_of_conduct.rst @@ -11,4 +11,3 @@ which includes all infrastructure used in the development of Python itself 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 index 149c548..ce22aed 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,43 +1,38 @@ [build-system] -requires = ["flit_core>=3.7"] build-backend = "flit_core.buildapi" +requires = [ + "flit_core>=3.7", +] -# project metadata [project] name = "python-docs-theme" -version = "2023.9" +version = "2024.1" description = "The Sphinx theme for the CPython docs and related projects" readme = "README.rst" -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" license.file = "LICENSE" +authors = [{name = "PyPA", email = "distutils-sig@python.org"}] requires-python = ">=3.8" - -# Classifiers list: https://pypi.org/classifiers/ classifiers = [ - "Development Status :: 5 - Production/Stable", - "Framework :: Sphinx :: Theme", - "Intended Audience :: Developers", - "License :: OSI Approved :: Python Software Foundation License", - "Operating System :: OS Independent", - "Topic :: Documentation", - "Topic :: Software Development :: Documentation", - "Programming Language :: Python", - "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.8", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Programming Language :: Python :: 3.13", + "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.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Topic :: Documentation", + "Topic :: Software Development :: Documentation", ] - -[[project.authors]] -name = "PyPA" -email = "distutils-sig@python.org" - +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" [project.entry-points."sphinx.html_themes"] python_docs_theme = 'python_docs_theme' diff --git a/python_docs_theme/__init__.py b/python_docs_theme/__init__.py index 0857b5f..7747675 100644 --- a/python_docs_theme/__init__.py +++ b/python_docs_theme/__init__.py @@ -1,8 +1,10 @@ +from __future__ import annotations + import hashlib import os from functools import lru_cache from pathlib import Path -from typing import Any, Dict, List +from typing import Any import sphinx.application from sphinx.builders.html import StandaloneHTMLBuilder @@ -19,7 +21,7 @@ def _asset_hash(path: str) -> str: return f"{path}?digest={digest}" -def _add_asset_hashes(static: List[str], add_digest_to: List[str]) -> None: +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 @@ -29,7 +31,7 @@ def _html_page_context( app: sphinx.application.Sphinx, pagename: str, templatename: str, - context: Dict[str, Any], + context: dict[str, Any], doctree: Any, ) -> None: if app.config.html_theme != "python_docs_theme": diff --git a/python_docs_theme/layout.html b/python_docs_theme/layout.html index 82b7ef4..d387ef3 100644 --- a/python_docs_theme/layout.html +++ b/python_docs_theme/layout.html @@ -14,7 +14,7 @@

{{ _('Navigation') }}

{%- endfor %} {%- block rootrellink %} -
  • python logo
    • +
  • {{ theme_root_icon_alt_text }}
  • {{theme_root_name}}{{ reldelim1 }}
  • @@ -71,7 +71,7 @@

    {{ _('Navigation') }}

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

    {{ _('Navigation') }}

    {%- if pagename != "search" and builder != "singlehtml" %} @@ -121,7 +121,7 @@

    {{ _('Navigation') }}

    {%- if logo %} {%- endif %} @@ -143,6 +143,7 @@

    {{ _('Navigation') }}

    {% trans %}Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.{% endtrans %}
    {% if theme_license_url %}{% trans license_file=theme_license_url %}See History and License for more information.{% endtrans %}
    {% endif %} + {% if theme_hosted_on %}{% trans hosted_on=theme_hosted_on %}Hosted on {{ hosted_on }}.{% endtrans %}
    {% endif %}
    {% include "footerdonate.html" %} diff --git a/python_docs_theme/static/menu.js b/python_docs_theme/static/menu.js index e233585..c7ab03e 100644 --- a/python_docs_theme/static/menu.js +++ b/python_docs_theme/static/menu.js @@ -54,4 +54,4 @@ document.addEventListener("DOMContentLoaded", function () { closeMenu() } }) -}) \ No newline at end of file +}) diff --git a/python_docs_theme/static/pydoctheme.css b/python_docs_theme/static/pydoctheme.css index ce032f1..14464db 100644 --- a/python_docs_theme/static/pydoctheme.css +++ b/python_docs_theme/static/pydoctheme.css @@ -29,6 +29,11 @@ pre { color: inherit; } +a[href] { + text-decoration: underline 1px; + text-underline-offset: 0.25em; +} + body { margin-left: 1em; margin-right: 1em; @@ -177,7 +182,7 @@ div.body { div.body p, div.body dd, div.body li, div.body blockquote { text-align: left; - line-height: 1.4; + line-height: 1.6; } div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 { margin: 0; diff --git a/python_docs_theme/static/pydoctheme_dark.css b/python_docs_theme/static/pydoctheme_dark.css index 46a2c7a..758d3de 100644 --- a/python_docs_theme/static/pydoctheme_dark.css +++ b/python_docs_theme/static/pydoctheme_dark.css @@ -60,6 +60,10 @@ span.highlighted { background-color: #616161; } +.footnote:target { + background-color: #2c3e50; +} + /* Below for most things in text */ dl.field-list > dt { diff --git a/python_docs_theme/theme.conf b/python_docs_theme/theme.conf index 564c9c5..1fbcabc 100644 --- a/python_docs_theme/theme.conf +++ b/python_docs_theme/theme.conf @@ -26,10 +26,12 @@ 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 =