FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-104818: Require Sphinx 6.2 to build the doc by vstinner · Pull Request #104819 · python/cpython · GitHub

/ cpython Public
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension .py  (2) .rst  (3) .txt  (2) .yml  (1) All 4 file types selected
Only manifest files
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
2 changes: 1 addition & 1 deletion .github/workflows/doc.yml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ jobs:
- name: 'Set up Python'
uses: actions/setup-python@v4
with:
python-version: '3.11' # known to work with Sphinx 3.2
python-version: '3.11' # known to work with Sphinx 6.2.1
cache: 'pip'
cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
- name: 'Install build dependencies'
Expand Down
5 changes: 3 additions & 2 deletions Doc/conf.py
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,9 @@
# By default, highlight as Python 3.
highlight_language = 'python3'

# Minimum version of sphinx required
needs_sphinx = '3.2'
# Minimum version of sphinx required.
# Sphinx 6.2 no longer uses imghdr which was removed in Python 3.13.
needs_sphinx = '6.2'
Comment thread
vstinner marked this conversation as resolved.

# Ignore any .rst files in the includes/ directory;
# they're embedded in pages but not rendered individually.
Expand Down
21 changes: 9 additions & 12 deletions Doc/requirements-oldest-sphinx.txt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,29 @@ blurb
python-docs-theme>=2022.1

# Generated from:
# pip install "Sphinx~=3.2.0" "docutils<0.17" "Jinja2<3" "MarkupSafe<2"
# pip install "Sphinx==6.2.0"
# pip freeze
#
# Sphinx 3.2 comes from ``needs_sphinx = '3.2'`` in ``Doc/conf.py``.
# Docutils<0.17, Jinja2<3, and MarkupSafe<2 are additionally specified as
# Sphinx 3.2 is incompatible with newer releases of these packages.
# Sphinx 6.2 comes from ``needs_sphinx = '6.2'`` in ``Doc/conf.py``.

Sphinx==3.2.1
alabaster==0.7.13
Babel==2.12.1
certifi==2022.12.7
certifi==2023.5.7
charset-normalizer==3.1.0
colorama==0.4.6
docutils==0.16
docutils==0.19
idna==3.4
imagesize==1.4.1
Jinja2==2.11.3
MarkupSafe==1.1.1
Jinja2==3.1.2
MarkupSafe==2.1.2
packaging==23.1
Pygments==2.15.1
requests==2.29.0
requests==2.31.0
snowballstemmer==2.2.0
Sphinx==6.2.0
sphinxcontrib-applehelp==1.0.4
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.1
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
urllib3==1.26.15
urllib3==2.0.2
2 changes: 1 addition & 1 deletion Doc/requirements.txt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
# Sphinx version is pinned so that new versions that introduce new warnings
# won't suddenly cause build failures. Updating the version is fine as long
# as no warnings are raised by doing so.
sphinx==4.5.0
sphinx==6.2.1

blurb

Expand Down
10 changes: 0 additions & 10 deletions Doc/tools/extensions/c_annotations.py
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
Expand Up @@ -42,16 +42,6 @@
}


# Monkeypatch nodes.Node.findall for forwards compatability
# This patch can be dropped when the minimum Sphinx version is 4.4.0
# or the minimum Docutils version is 0.18.1.
if docutils.__version_info__ < (0, 18, 1):
def findall(self, *args, **kwargs):
return iter(self.traverse(*args, **kwargs))

nodes.Node.findall = findall


class RCEntry:
def __init__(self, name):
self.name = name
Expand Down
2 changes: 2 additions & 0 deletions Doc/using/configure.rst
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ Features required to build CPython:

* On Windows, Microsoft Visual Studio 2017 or later is required.

* Sphinx 6.2 or newer is required to build the Python documentation.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

This seems a bit out of place here to me, but I don't have a better suggestion for where to put it off the top of my head. Do we actually mention building the documentation elsewhere in the docs? I can't find one with a short search.

CAM-Gerlach May 25, 2023
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Yeah, I agree—it seems quite out of place here. The meta-documentation for the docs themselves lives in the devguide, and this mention should presumably go there under the appropriate section.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I'd prefer to avoid mentioning the Sphinx version in the devguide and needing to keep it in sync. It's defined in the requirements.txt so whatever is needed will be installed as required. Plus it's different for older branches.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Are you saying that the whole section "Build Requirements" is irrelevant in Python documentation. Or that mentioning the minimum Sphinx version in "Build Requirements" is irrelevant?

For me, it's convenient to have the same repository where we actually specify needs_sphinx (Doc/conf.py) and we clearly document that version. Having two Git repositories just make it less pratical.

Do we actually mention building the documentation elsewhere in the docs?

I added this section recently. I wrote "Sphinx 6.2 or newer is required to build the Python documentation." If someone doesn't care about the doc, this sentence can be ignored.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I'd prefer to avoid mentioning the Sphinx version in the devguide and needing to keep it in sync. It's defined in the requirements.txt so whatever is needed will be installed as required. Plus it's different for older branches.

FWIW, on second thought I agree, and in fact it was I that removed the references to such recently when overhauling the section I linked. We could mention the files the requirements are defined in, though, and directly link them with the :cpy-file: role. That would allow users to easily check the versions for their desired branch without having to duplicate them multiple places, which will inevitably get out of sync.


.. versionchanged:: 3.11
C11 compiler, IEEE 754 and NaN support are now required.
On Windows, Visual Studio 2017 or later is required.
Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.13.rst
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,11 @@ that may require changes to your code.
Build Changes
=============

* Sphinx 6.2 or newer is now required to build the Python documentation.
Sphinx 6.2 no longer uses the :mod:`!imghdr` module which was removed in
Python 3.13.
(Contributed by Victor Stinner in :gh:`104818`.)


C API Changes
=============
Expand Down
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Sphinx 6.2 or newer is now required to build the Python documentation. Patch
by Victor Stinner.

Back | FazBrowse Home | New Git URL