Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Note minimum requirements for Sphinx #216

Merged
merged 3 commits into from
Jan 28, 2025
Merged

Note minimum requirements for Sphinx #216

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2f4ab24
Note minimum requirements for Sphinx
AA-Turner Jan 27, 2025
74f3ff8
Update pre-commit to fix a warning
AA-Turner Jan 27, 2025
4eaf005
Enforce runtime requirements
AA-Turner Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand Down
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In another project we noticed the Python version mentioned in docs said 3.6+, but in reality it's 3.9+ and we'd forgotten to update that three times!

To DRY, perhaps we don't need to document this in words, seeing as we have definitive metadata in pyproject.toml?

That is:

requires-python = ">=3.9"
...
dependencies = [
  "sphinx>=3.4",
]

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose I put it in the README to make it very clear -- perhaps we could replace it with a policy statement instead? I.e.:

"It supports all Sphinx versions required by the stable Python branches."

I'm not a huge fan of this wording, though -- it feels clunky.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, it's okay to leave this in the README if you like, at least it's the repo's first page and not some other "hidden"/forgotten docs page.


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
4 changes: 4 additions & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ classifiers = [
"Topic :: Documentation",
"Topic :: Software Development :: Documentation",
]
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/"
Expand Down
2 changes: 2 additions & 0 deletions python_docs_theme/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ def _html_page_context(


def setup(app):
app.require_sphinx("3.4")

current_dir = os.path.abspath(os.path.dirname(__file__))
app.add_html_theme("python_docs_theme", current_dir)

Expand Down
Loading