DOC: Bump minimum Sphinx to 5.1.0 #28627
Merged
Conversation
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
timhoffm
approved these changes
Jul 30, 2024
doc/api/next_api_changes/README.rst
Outdated
Comment on lines
3
to
5
| .. NOTE | ||
| Lines 9-end of this file are include in :ref:`api_whats_new`; | ||
| therefore, please check the doc build after changing this file. |
There was a problem hiding this comment.
Suggested change
| .. NOTE | |
| Lines 9-end of this file are include in :ref:`api_whats_new`; | |
| therefore, please check the doc build after changing this file. | |
| .. NOTE TO EDITORS OF THIS FILE | |
| This file serves as README directly available in the file system next to the | |
| next_api_changes entries. Its content, starting line 11 (after the heading), | |
| is additionally included in the documentation page doc/devel/api_changes.rst. | |
| Please check that the page builds correctly after changing this file. |
I think it helps to be a bit more explicit. Also, the ref does not help much
because readers will ever only see this not in source. Instead, state the
file we're embedding in.
When you accept this, please adapt the include line to 11.
Optional alternatives to specifying a start-line, which may get out of sync:
- turn the "heading" into a comment
.. Adding API change notes ======================= - Remove the heading from
api_changes.rstand include the heading from here.
There was a problem hiding this comment.
I think if this is being changed anyway, maybe move to using comment guards so don't need to care about lines:
.. api-change-guide-start
API change notes for future releases are collected in
:file:`next_api_changes`. They are divided into four subdirectories:
more content....
.. api-change-guide-end
.. include:: ../users/next_whats_new/README.rst
:start-after: api-change-guide-start
:end-before: api-change-guide-end
doc/users/next_whats_new/README.rst
Outdated
Comment on lines
3
to
5
| .. NOTE | ||
| Lines 9-end of this file are include in :ref:`api_whats_new`; | ||
| therefore, please check the doc build after changing this file. |
There was a problem hiding this comment.
Suggested change
| .. NOTE | |
| Lines 9-end of this file are include in :ref:`api_whats_new`; | |
| therefore, please check the doc build after changing this file. | |
| .. NOTE TO EDITORS OF THIS FILE | |
| This file serves as README directly available in the file system next to the | |
| next_whats_new entries. Its content, starting line 11 (after the heading), | |
| is additionally included in the documentation page doc/devel/api_changes.rst. | |
| Please check that the page builds correctly after changing this file. |
as above
timhoffm
reviewed
Jul 30, 2024
doc/missing-references.json
Outdated
| ] | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Suggested change
| } | |
| } | |
to placate pre-commit.
We depend on `pydata-sphinx-theme` 0.15.0, which requires Sphinx 5, and `sphinx-tags`, which requires Sphinx 5.1, so we really shouldn't create an environment with Sphinx older than that.
Its use was removed in matplotlib#11451.
story645
approved these changes
Jul 31, 2024
doc/api/next_api_changes/README.rst
Outdated
| @@ -1,10 +1,18 @@ | |||
| :orphan: | |||
|
|
|||
| .. NOTE TO EDITORS OF THIS FILE | |||
| This file serves as README directly available in the file system next to the | |||
There was a problem hiding this comment.
Suggested change
| This file serves as README directly available in the file system next to the | |
| This file serves as the README directly available in the file system next to the |
doc/api/next_api_changes/README.rst
Outdated
| @@ -1,10 +1,18 @@ | |||
| :orphan: | |||
|
|
|||
| .. NOTE TO EDITORS OF THIS FILE | |||
| This file serves as README directly available in the file system next to the | |||
| next_api_changes entries. Its content, between the ``api-change-guide-*`` markers, is | |||
There was a problem hiding this comment.
Suggested change
| next_api_changes entries. Its content, between the ``api-change-guide-*`` markers, is | |
| next_api_changes entries. The content between the ``api-change-guide-*`` markers is |
It's not really a parenthetical clause
doc/users/next_whats_new/README.rst
Outdated
| @@ -1,9 +1,19 @@ | |||
| :orphan: | |||
|
|
|||
| .. NOTE TO EDITORS OF THIS FILE | |||
| This file serves as README directly available in the file system next to the | |||
There was a problem hiding this comment.
Suggested change
| This file serves as README directly available in the file system next to the | |
| This file serves as the README directly available in the file system next to the |
doc/users/next_whats_new/README.rst
Outdated
| < 8000 /td> | @@ -1,9 +1,19 @@ | ||
| :orphan: | |||
|
|
|||
| .. NOTE TO EDITORS OF THIS FILE | |||
| This file serves as README directly available in the file system next to the | |||
| next_whats_new entries. Its content, between the ``whats-new-guide-*`` markers, is | |||
There was a problem hiding this comment.
Suggested change
| next_whats_new entries. Its content, between the ``whats-new-guide-*`` markers, is | |
| next_whats_new entries. The content between the ``whats-new-guide-*`` markers is |
Sphinx 3.4 added a `warn-missing-reference` event, from which we can: 1. record the missing reference, avoiding any of the messing about with logging, and; 2. suppress the warning, avoiding any messing about with the `nitpicky_ignore` settings and their changing defaults. Also, simplify some of the callbacks by simply not connect the events if not necessary, instead of checking in every one.
timhoffm
approved these changes
Jul 31, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR summary
We depend on
pydata-sphinx-theme0.15.0, which requires Sphinx 5, andsphinx-tags, which requires Sphinx 5.1, so we really shouldn't create an environment with Sphinx older than that. This also enables simplifying the missing-references extension with the newwarn-missing-referenceevent.Clean up some unused templates / missing references to go along with that, and fix the include of next API changes/what's new instructions.
PR checklist