8000 DOC: Bump minimum Sphinx to 5.1.0 by QuLogic · Pull Request #28627 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]

Skip to content

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

Merged
merged 5 commits into from
Jul 31, 2024
Merged

DOC: Bump minimum Sphinx to 5.1.0 #28627

merged 5 commits into from
Jul 31, 2024

Conversation

QuLogic
Copy link
Member
@QuLogic QuLogic commented Jul 30, 2024

PR summary

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. This also enables simplifying the missing-references extension with the new warn-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

Copy link
Member
@timhoffm timhoffm left a 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.

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.
Copy link
Member

Choose a reason for hiding this comment

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

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.rst and include the heading from here.

Copy link
Member
@story645 story645 Jul 30, 2024

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

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.
Copy link
Member

Choose a reason for hiding this comment

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

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

]
}
}
}
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
}
}

to placate pre-commit.

QuLogic added 3 commits July 30, 2024 18:15
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.
Copy link
Member
@story645 story645 left a 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!

@@ -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
Copy link
Member

Choose a reason for hiding this comment

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

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

@@ -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
Copy link
Member

Choose a reason for hiding this comment

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

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

@@ -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
Copy link
Member

Choose a reason for hiding this comment

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

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

@@ -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
Copy link
Member

Choose a reason for hiding this comment

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

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

QuLogic added 2 commits July 30, 2024 22:30
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 timhoffm merged commit < 8EFF a href="/matplotlib/matplotlib/commit/ae2d89002d6c394ed39a1e84075eb4e86e593c99">ae2d890 into matplotlib:main Jul 31, 2024
39 checks passed
@QuLogic QuLogic deleted the sphinx510 branch July 31, 2024 04:27
@QuLogic QuLogic added this to the v3.10.0 milestone Sep 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants
0