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

Jump to bottom

gh-104818: Require Sphinx 6.2 to build the doc #104819

Closed
wants to merge 3 commits into from
Closed

gh-104818: Require Sphinx 6.2 to build the doc #104819

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
acc5c47
gh-104818: Require Sphinx 6.2 to build the doc
vstinner May 23, 2023
9d8ff71
Elaborate comments
vstinner May 25, 2023
b645426
Fix requirements-oldest-sphinx.txt
vstinner May 25, 2023
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
2 changes: 1 addition & 1 deletion .github/workflows/doc.yml
View file
Open in desktop
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
View file
Open in desktop
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'
vstinner marked this conversation as resolved.
Show resolved Hide 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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@

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

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

Choose a reason for hiding this comment

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

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.

Copy link
Member

@CAM-Gerlach CAM-Gerlach May 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

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
Member

Choose a reason for hiding this comment

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

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
Member Author

Choose a reason for hiding this comment

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

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
Member

Choose a reason for hiding this comment

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

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 Expand Up @@ -59,7 +61,7 @@

.. cmdoption:: --enable-loadable-sqlite-extensions

Support loadable extensions in the :mod:`_sqlite` extension module (default

Check warning on line 64 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:mod reference target not found: _sqlite
is no).

See the :meth:`sqlite3.Connection.enable_load_extension` method of the
Expand Down Expand Up @@ -155,7 +157,7 @@
Directory of wheel packages used by the :mod:`ensurepip` module
(none by default).

Some Linux distribution packaging policies recommend against bundling

Check warning on line 160 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:mod reference target not found: ensurepip._bundled
dependencies. For example, Fedora installs wheel packages in the
``/usr/share/python-wheels/`` directory and don't install the
:mod:`ensurepip._bundled` package.
Expand Down Expand Up @@ -234,7 +236,7 @@

.. cmdoption:: --disable-test-modules

Don't build nor install test modules, like the :mod:`test` package or the

Check warning on line 239 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:mod reference target not found: _testcapi
:mod:`_testcapi` extension module (built and installed by default).

.. versionadded:: 3.10
Expand Down Expand Up @@ -368,7 +370,7 @@
* Display all warnings by default: the list of default warning filters is empty
in the :mod:`warnings` module.
* Add ``d`` to :data:`sys.abiflags`.
* Add :func:`sys.gettotalrefcount` function.

Check warning on line 373 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:func reference target not found: sys.gettotalrefcount
* Add :option:`-X showrefcount <-X>` command line option.
* Add :option:`-d` command line option and :envvar:`PYTHONDEBUG` environment
variable to debug the parser.
Expand All @@ -390,7 +392,7 @@
* Check that deallocator functions don't change the current exception.
* The garbage collector (:func:`gc.collect` function) runs some basic checks
on objects consistency.
* The :c:macro:`Py_SAFE_DOWNCAST()` macro checks for integer underflow and

Check warning on line 395 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

c:macro reference target not found: Py_SAFE_DOWNCAST()
overflow when downcasting from wide types to narrow types.

See also the :ref:`Python Development Mode <devmode>` and the
Expand Down Expand Up @@ -418,7 +420,7 @@
Effects:

* Define the ``Py_TRACE_REFS`` macro.
* Add :func:`sys.getobjects` function.

Check warning on line 423 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:func reference target not found: sys.getobjects
* Add :envvar:`PYTHONDUMPREFS` environment variable.

This build is not ABI compatible with release build (default build) or debug
Expand Down Expand Up @@ -496,7 +498,7 @@

.. cmdoption:: --with-system-expat

Build the :mod:`pyexpat` module using an installed ``expat`` library

Check warning on line 501 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:mod reference target not found: pyexpat
(default is no).

.. cmdoption:: --with-system-libmpdec
Expand Down Expand Up @@ -748,10 +750,10 @@
At the beginning of the files, C extensions are built as built-in modules.
Extensions defined after the ``*shared*`` marker are built as dynamic libraries.

The :file:`setup.py` script only builds C extensions as shared libraries using

Check warning on line 753 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

py:mod reference target not found: distutils
the :mod:`distutils` module.

The :c:macro:`PyAPI_FUNC()`, :c:macro:`PyAPI_API()` and

Check warning on line 756 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

c:macro reference target not found: PyAPI_FUNC()

Check warning on line 756 in Doc/using/configure.rst

View workflow job for this annotation

GitHub Actions / Docs 

c:macro reference target not found: PyAPI_API()
:c:macro:`PyMODINIT_FUNC()` macros of :file:`Include/pyport.h` are defined
differently depending if the ``Py_BUILD_CORE_MODULE`` macro is defined:

Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.13.rst
View file
Open in desktop
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
2 changes: 2 additions & 0 deletions Misc/NEWS.d/next/Build/2023-05-23-22-41-42.gh-issue-104818.8SI01U.rst
View file
Open in desktop
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.
Loading