-
-
Notifications
You must be signed in to change notification settings - Fork 7.9k
DOC: Bump minimum Sphinx to 5.1.0 #28627
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.
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
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Optional improvements to the READMEs.
doc/api/next_api_changes/README.rst
Outdated
.. 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
.. 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.rst
and include the heading from here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
.. 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
.. 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
doc/missing-references.json
Outdated
] | ||
} | ||
} | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
} | |
} | |
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Grammar nits but otherwise yay cleaner code!
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
@@ -1,9 8000 +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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
ae2d890
into
matplotlib:main
PR summary
We depend on
pydata-sphinx-theme
0.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-reference
event.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