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
Show file tree
Hide file tree
Changes from all commits
Commits
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
22 changes: 0 additions & 22 deletions doc/_templates/autofunctions.rst

This file was deleted.

16 changes: 11 additions & 5 deletions doc/api/next_api_changes/README.rst
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
:orphan:

.. NOTE TO EDITORS OF THIS FILE
This file serves as the README directly available in the file system next to the
next_api_changes entries. The content between the ``api-change-guide-*`` markers is
additionally included in the documentation page ``doc/devel/api_changes.rst``. Please
check that the page builds correctly after changing this file.

Adding API change notes
=======================

API change notes for future releases are collected in
:file:`next_api_changes`. They are divided into four subdirectories:
.. api-change-guide-start

API change notes for future releases are collected in :file:`doc/api/next_api_changes/`.
They are divided into four subdirectories:

- **Deprecations**: Announcements of future changes. Typically, these will
raise a deprecation warning and users of this API should change their code
Expand Down Expand Up @@ -33,6 +41,4 @@ Please avoid using references in section titles, as it causes links to be
confusing in the table of contents. Instead, ensure that a reference is
included in the descriptive text.

.. NOTE
Lines 5-30 of this file are include in :ref:`api_whats_new`;
therefore, please check the doc build after changing this file.
.. api-change-guide-end
4 changes: 2 additions & 2 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -360,8 +360,8 @@ def gallery_image_warning_filter(record):
# This is the default encoding, but it doesn't hurt to be explicit
source_encoding = "utf-8"

# The toplevel toctree document (renamed to root_doc in Sphinx 4.0)
root_doc = master_doc = 'index'
# The toplevel toctree document.
root_doc = 'index'

# General substitutions.
try:
Expand Down
8 changes: 4 additions & 4 deletions doc/devel/api_changes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -216,14 +216,14 @@ API change notes
""""""""""""""""

.. include:: ../api/next_api_changes/README.rst
:start-line: 5
:end-line: 31
:start-after: api-change-guide-start
:end-before: api-change-guide-end

.. _whats-new-notes:

What's new notes
""""""""""""""""

.. include:: ../users/next_whats_new/README.rst
:start-line: 5
:end-line: 24
:start-after: whats-new-guide-start
:end-before: whats-new-guide-end
169 changes: 73 additions & 96 deletions doc/missing-references.json

Large diffs are not rendered by default.

162 changes: 46 additions & 116 deletions doc/sphinxext/missing_references.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,71 +17,16 @@

from collections import defaultdict
import json
import logging
from pathlib import Path

from docutils.utils import get_source_line
from docutils import nodes
from sphinx.util import logging as sphinx_logging

import matplotlib

logger = sphinx_logging.getLogger(__name__)


class MissingReferenceFilter(logging.Filter):
"""
A logging filter designed to record missing reference warning messages
for use by this extension
"""
def __init__(self, app):
self.app = app
super().__init__()

def _record_reference(self, record):
if not (getattr(record, 'type', '') == 'ref' and
isinstance(getattr(record, 'location', None), nodes.Node)):
return

if not hasattr(self.app.env, "missing_references_warnings"):
self.app.env.missing_references_warnings = defaultdict(set)

record_missing_reference(self.app,
self.app.env.missing_references_warnings,
record.location)

def filter(self, record):
self._record_reference(record)
return True


def record_missing_reference(app, record, node):
domain = node["refdomain"]
typ = node["reftype"]
target = node["reftarget"]
location = get_location(node, app)

domain_type = f"{domain}:{typ}"

record[(domain_type, target)].add(location)


def record_missing_reference_handler(app, env, node, contnode):
"""
When the sphinx app notices a missing reference, it emits an
event which calls this function. This function records the missing
references for analysis at the end of the sphinx build.
"""
if not app.config.missing_references_enabled:
# no-op when we are disabled.
return

if not hasattr(env, "missing_references_events"):
env.missing_references_events = defaultdict(set)

record_missing_reference(app, env.missing_references_events, node)


def get_location(node, app):
"""
Given a docutils node and a sphinx application, return a string
Expand Down Expand Up @@ -146,10 +91,34 @@ def _truncate_location(location):
return location.split(":", 1)[0]


def _warn_unused_missing_references(app):
if not app.config.missing_references_warn_unused_ignores:
return
def handle_missing_reference(app, domain, node):
"""
9E88 Handle the warn-missing-reference Sphinx event.

This function will:

#. record missing references for saving/comparing with ignored list.
#. prevent Sphinx from raising a warning on ignored references.
"""
typ = node["reftype"]
target = node["reftarget"]
location = get_location(node, app)
domain_type = f"{domain.name}:{typ}"

app.env.missing_references_events[(domain_type, target)].add(location)

# If we're ignoring this event, return True so that Sphinx thinks we handled it,
# even though we didn't print or warn. If we aren't ignoring it, Sphinx will print a
# warning about the missing reference.
if location in app.env.missing_references_ignored_references.get(
(domain_type, target), []):
return True


def warn_unused_missing_references(app, exc):
"""
Check that all lines of the existing JSON file are still necessary.
"""
# We can only warn if we are building from a source install
# otherwise, we just have to skip this step.
basepath = Path(matplotlib.__file__).parent.parent.parent.resolve()
Expand All @@ -159,9 +128,8 @@ def _warn_unused_missing_references(app):
return

# This is a dictionary of {(domain_type, target): locations}
references_ignored = getattr(
app.env, 'missing_references_ignored_references', {})
references_events = getattr(app.env, 'missing_references_events', {})
references_ignored = app.env.missing_references_ignored_references
references_events = app.env.missing_references_events

# Warn about any reference which is no longer missing.
for (domain_type, target), locations in references_ignored.items():
Expand All @@ -184,26 +152,13 @@ def _warn_unused_missing_references(app):
subtype=domain_type)


def save_missing_references_handler(app, exc):
def save_missing_references(app, exc):
"""
At the end of the sphinx build, check that all lines of the existing JSON
file are still necessary.

If the configuration value ``missing_references_write_json`` is set
then write a new JSON file containing missing references.
Write a new JSON file containing missing references.
"""
if not app.config.missing_references_enabled:
# no-op when we are disabled.
return

_warn_unused_missing_references(app)

json_path = Path(app.confdir) / app.config.missing_references_filename

references_warnings = getattr(app.env, 'missing_references_warnings', {})

if app.config.missing_references_write_json:
_write_missing_references_json(references_warnings, json_path)
references_warnings = app.env.missing_references_events
_write_missing_references_json(references_warnings, json_path)


def _write_missing_references_json(records, json_path):
Expand All @@ -220,6 +175,7 @@ def _write_missing_references_json(records, json_path):
transformed_records[domain_type][target] = sorted(paths)
with json_path.open("w") as stream:
json.dump(transformed_records, stream, sort_keys=True, indent=2)
stream.write("\n") # Silence pre-commit no-newline-at-end-of-file warning.


def _read_missing_references_json(json_path):
Expand All @@ -242,49 +198,25 @@ def _read_missing_references_json(json_path):
return ignored_references


def prepare_missing_references_handler(app):
def prepare_missing_references_setup(app):
"""
Handler called to initialize this extension once the configuration
is ready.

Reads the missing references file and populates ``nitpick_ignore`` if
appropriate.
Initialize this extension once the configuration is ready.
"""
if not app.config.missing_references_enabled:
# no-op when we are disabled.
return

sphinx_logger = logging.getLogger('sphinx')
missing_reference_filter = MissingReferenceFilter(app)
for handler in sphinx_logger.handlers:
if (isinstance(handler, sphinx_logging.WarningStreamHandler)
and missing_reference_filter not in handler.filters):

# This *must* be the first filter, because subsequent filters
# throw away the node information and then we can't identify
# the reference uniquely.
handler.filters.insert(0, missing_reference_filter)

app.env.missing_references_ignored_references = {}
app.connect("warn-missing-reference", handle_missing_reference)
if app.config.missing_references_warn_unused_ignores:
app.connect("build-finished", warn_unused_missing_references)
if app.config.missing_references_write_json:
app.connect("build-finished", save_missing_references)

json_path = Path(app.confdir) / app.config.missing_references_filename
if not json_path.exists():
return

ignored_references = _read_missing_references_json(json_path)

app.env.missing_references_ignored_references = ignored_references

# If we are going to re-write the JSON file, then don't suppress missing
# reference warnings. We want to record a full list of missing references
# for use later. Otherwise, add all known missing references to
# ``nitpick_ignore```
if not app.config.missing_references_write_json:
# Since Sphinx v6.2, nitpick_ignore may be a list, set or tuple, and
# defaults to set. Previously it was always a list. Cast to list for
# consistency across versions.
app.config.nitpick_ignore = list(app.config.nitpick_ignore)
app.config.nitpick_ignore.extend(ignored_references.keys())
app.env.missing_references_ignored_references = (
_read_missing_references_json(json_path) if json_path.exists() else {}
)
app.env.missing_references_events = defaultdict(set)


def setup(app):
Expand All @@ -294,8 +226,6 @@ def setup(app):
app.add_config_value("missing_references_filename",
"missing-references.json", "env")

app.connect("builder-inited", prepare_missing_references_handler)
app.connect("missing-reference", record_missing_reference_handler)
app.connect("build-finished", save_missing_references_handler)
app.connect("builder-inited", prepare_missing_references_setup)

return {'parallel_read_safe': True}
16 changes: 12 additions & 4 deletions doc/users/next_whats_new/README.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,19 @@
:orphan:

.. NOTE TO EDITORS OF THIS FILE
This file serves as the README directly available in the file system next to the
next_whats_new entries. The content between the ``whats-new-guide-*`` markers is
additionally included in the documentation page ``doc/devel/api_changes.rst``. Please
check that the page builds correctly after changing this file.


Instructions for writing "What's new" entries
=============================================

Please place new portions of `whats_new.rst` in the `next_whats_new` directory.
.. whats-new-guide-start

Please place new portions of :file:`whats_new.rst` in the
:file:`doc/users/next_whats_new/` directory.

When adding an entry please look at the currently existing files to
see if you can extend any of them. If you create a file, name it
Expand All @@ -26,6 +36,4 @@ Please avoid using references in section titles, as it causes links to be
confusing in the table of contents. Instead, ensure that a reference is
included in the descriptive text.

.. NOTE
Lines 5-24 of this file are include in :ref:`api_whats_new`;
therefore, please check the doc build after changing this file.
.. whats-new-guide-end
2 changes: 1 addition & 1 deletion lib/matplotlib/axes/_base.py
Original file line number Diff line number Diff line change
Expand Up @@ -2635,7 +2635,7 @@ def set_autoscale_on(self, b):
@property
def use_sticky_edges(self):
"""
When autoscaling, whether to obey all `Artist.sticky_edges`.
When autoscaling, whether to obey all `.Artist.sticky_edges`.

Default is ``True``.

Expand Down
2 changes: 1 addition & 1 deletion lib/matplotlib/backend_bases.py
558
Original file line numberDiff line number Diff line change
Expand Up @@ -3419,7 +3419,7 @@ def remove_toolitem(self, name):

This hook must be implemented in each backend and contains the
backend-specific code to remove an element from the toolbar; it is
called when `.ToolManager` emits a `tool_removed_event`.
called when `.ToolManager` emits a ``tool_removed_event``.

Because some tools are present only on the `.ToolManager` but not on
the `ToolContainer`, this method must be a no-op when called on a tool
Expand Down
4 changes: 2 additions & 2 deletions lib/matplotlib/backends/backend_template.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@
import matplotlib
matplotlib.use("module://my.backend")

If your backend implements support for saving figures (i.e. has a `print_xyz`
method), you can register it as the default handler for a given file type::
If your backend implements support for saving figures (i.e. has a ``print_xyz`` method),
you can register it as the default handler for a given file type::

from matplotlib.backend_bases import register_backend
register_backend('xyz', 'my_backend', 'XYZ File Format')
Expand Down
2 changes: 1 addition & 1 deletion lib/matplotlib/testing/decorators.py
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ def image_comparison(baseline_images, extensions=None, tol=0,
style=("classic", "_classic_test_patch")):
"""
Compare images generated by the test with those specified in
*baseline_images*, which must correspond, else an `ImageComparisonFailure`
*baseline_images*, which must correspond, else an `.ImageComparisonFailure`
exception will be raised.

Parameters
Expand Down
2 changes: 1 addition & 1 deletion requirements/doc/doc-requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
# Install the documentation requirements with:
# pip install -r requirements/doc/doc-requirements.txt
#
sphinx>=3.0.0,!=6.1.2
sphinx>=5.1.0,!=6.1.2
colorspacious
ipython
ipywidgets
Expand Down
Loading
0