Skip to content

Backport PR #23641 on branch v3.5.3-doc (Fix doc bugs found in 3.5.3) #23652

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

Merged
merged 1 commit into from
Aug 17, 2022
Merged

Backport PR #23641 on branch v3.5.3-doc (Fix doc bugs found in 3.5.3) #23652

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions doc/devel/MEP/MEP14.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,8 @@ number of other projects:
- `Microsoft DirectWrite`_
- `Apple Core Text`_

.. _pango: https://www.pango.org/
.. _harfbuzz: https://www.freedesktop.org/wiki/Software/HarfBuzz/
.. _pango: https://pango.gnome.org
.. _harfbuzz: https://github.com/harfbuzz/harfbuzz
.. _QtTextLayout: https://doc.qt.io/archives/qt-4.8/qtextlayout.html
.. _Microsoft DirectWrite: https://docs.microsoft.com/en-ca/windows/win32/directwrite/introducing-directwrite
.. _Apple Core Text: https://developer.apple.com/library/archive/documentation/StringsTextFonts/Conceptual/CoreText_Programming/Overview/Overview.html
Expand Down
2 changes: 1 addition & 1 deletion doc/devel/MEP/MEP29.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ one has to look at the gallery where one such example is provided:
This example takes a list of strings as well as a list of colors which makes it
cumbersome to use. An alternative would be to use a restricted set of pango_-like markup and to interpret this markup.

.. _pango: https://developer.gnome.org/pygtk/stable/pango-markup-language.html
.. _pango: https://docs.gtk.org/Pango/pango_markup.html#pango-markup

Some markup examples::

Expand Down
4 changes: 2 additions & 2 deletions doc/devel/dependencies.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ Font handling and rendering

* `LaTeX <https://www.latex-project.org/>`_ (with `cm-super
<https://ctan.org/pkg/cm-super>`__ ) and `GhostScript (>=9.0)
<https://ghostscript.com/download/>`_ : for rendering text with LaTeX.
<https://ghostscript.com/releases/>`_ : for rendering text with LaTeX.
* `fontconfig <https://www.fontconfig.org>`_ (>= 2.7): for detection of system
fonts on Linux.

Expand Down Expand Up @@ -191,7 +191,7 @@ Optional:
- pytest-xdist_ to run tests in parallel

.. _pytest: http://doc.pytest.org/en/latest/
.. _Ghostscript: https://www.ghostscript.com/
.. _Ghostscript: https://ghostscript.com/
.. _Inkscape: https://inkscape.org
.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/
.. _pytest-flake8: https://pypi.org/project/pytest-flake8/
Expand Down
91 changes: 47 additions & 44 deletions doc/devel/style_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ reliability and consistency in documentation. They are not interchangeable.
+------------------+--------------------------+--------------+--------------+
| Term | Description | Correct | Incorrect |
+==================+==========================+==============+==============+
| Figure_ | Matplotlib working space | - *For | - "The figure|
| |Figure| | Matplotlib working space | - *For | - "The figure|
| | for programming. | Matplotlib | is the |
| | | objects*: | working |
| | | Figure, | space for |
Expand All @@ -39,11 +39,11 @@ reliability and consistency in documentation. They are not interchangeable.
| | | space for | provide the|
| | | the visual.| visuals." |
| | | - *Referring | - "The |
| | | to class*: | Figure_ |
| | | Figure_ , | Four |
| | | to class*: | |Figure| |
| | | |Figure|, | Four |
| | | "Methods | leglock is |
| | | within the | a wrestling|
| | | Figure_ | move." |
| | | |Figure| | move." |
| | | provide the| |
| | | visuals." | |
| | | - *General | |
Expand All @@ -55,28 +55,29 @@ reliability and consistency in documentation. They are not interchangeable.
| | | figure | |
| | | skater." | |
+------------------+--------------------------+--------------+--------------+
| Axes_ | Subplots within Figure. | - *For | - "The axes |
| |Axes| | Subplots within Figure. | - *For | - "The axes |
| | Contains plot elements | Matplotlib | methods |
| | and is responsible for | objects*: | transform |
| | plotting and configuring | Axes, "An | the data." |
| | additional details. | Axes is a | - "Each Axes_|
| | | subplot | is specific|
| | | within the | to a |
| | | Figure." | Figure." |
| | additional details. | Axes is a | - "Each |
| | | subplot | |Axes| is |
| | | within the | specific to|
| | | Figure." | a Figure." |
| | | - *Referring | - "The |
| | | to class*: | musicians |
| | | Axes_ , | on stage |
| | | "Each Axes_| call their |
| | | is specific| guitars |
| | | to one | Axes." |
| | | Figure." | - "The point |
| | | - *General | where the |
| | | language*: | Axes meet |
| | | axes, "Both| is the |
| | | loggers and| origin of |
| | | lumberjacks| the |
| | | use axes to| coordinate |
| | | chop wood."| system." |
| | | |Axes|, | on stage |
| | | "Each | call their |
| | | |Axes| is | guitars |
| | | specific to| Axes." |
| | | one | - "The point |
| | | Figure." | where the |
| | | - *General | Axes meet |
| | | language*: | is the |
| | | axes, "Both| origin of |
| | | loggers and| the |
| | | lumberjacks| coordinate |
| | | use axes to| system." |
| | | chop wood."| |
| | | OR "There | |
| | | are no | |
| | | standard | |
Expand All @@ -89,24 +90,25 @@ reliability and consistency in documentation. They are not interchangeable.
| | | (Plural of | |
| | | axis) | |
+------------------+--------------------------+--------------+--------------+
| Artist_ | Broad variety of | - *For | - "Configure |
| |Artist| | Broad variety of | - *For | - "Configure |
| | Matplotlib objects that | Matplotlib | the legend |
| | display visuals. | objects*: | artist with|
| | | Artist, | its |
| | | "Artists | respective |
| | | display | method." |
| | | visuals and| - "There is |
| | | are the | an Artist_ |
| | | visible | for that |
| | | elements | visual in |
| | | when the | the graph."|
| | | rendering | - "Some |
| | | a Figure." | Artists |
| | | - *Referring | became |
| | | to class*: | famous only|
| | | Artist_ , | by |
| | | "Each | accident." |
| | | Artist_ has| |
| | | are the | an |
| | | visible | |Artist| |
| | | elements | for that |
| | | when | visual in |
| | | rendering a| the graph."|
| | | Figure." | - "Some |
| | | - *Referring | Artists |
| | | to class*: | became |
| | | |Artist| , | famous only|
| | | "Each | by |
| | | |Artist| | accident." |
| | | has | |
| | | respective | |
| | | methods and| |
| | | functions."| |
Expand All @@ -119,7 +121,7 @@ reliability and consistency in documentation. They are not interchangeable.
| | | is from | |
| | | France." | |
+------------------+--------------------------+--------------+--------------+
| Axis_ | Human-readable single | - *For | - "Plot the |
| |Axis| | Human-readable single | - *For | - "Plot the |
| | dimensional object | Matplotlib | graph onto |
| | of reference marks | objects*: | the axis." |
| | containing ticks, tick | Axis, "The | - "Each Axis |
Expand All @@ -133,12 +135,13 @@ reliability and consistency in documentation. They are not interchangeable.
| | | objects) | - "In some |
| | | - *Referring | computer |
| | | to class*: | graphics |
| | | Axis_ , | contexts, |
| | | "The Axis_ | the |
| | | contains | ordinate |
| | | respective | Axis_ may |
| | | XAxis and | be oriented|
| | | YAxis | downwards."|
| | | |Axis|, | contexts, |
| | | "The | the |
| | | |Axis| | ordinate |
| | | contains | |Axis| may |
| | | respective | be oriented|
| | | XAxis and | downwards."|
| | | YAxis | |
| | | objects." | |
| | | - *General | |
| | | language*: | |
Expand All @@ -162,10 +165,10 @@ reliability and consistency in documentation. They are not interchangeable.
| | | | interface |
+------------------+--------------------------+--------------+--------------+

.. _Figure: :class:`~matplotlib.figure.Figure`
.. _Axes: :class:`~matplotlib.axes.Axes`
.. _Artist: :class:`~matplotlib.artist.Artist`
.. _Axis: :class:`matplotlib.axis.Axis`
.. |Figure| replace:: :class:`~matplotlib.figure.Figure`
.. |Axes| replace:: :class:`~matplotlib.axes.Axes`
.. |Artist| replace:: :class:`~matplotlib.artist.Artist`
.. |Axis| replace:: :class:`~matplotlib.axis.Axis`


Grammar
Expand Down
2 changes: 1 addition & 1 deletion doc/devel/triage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ The following workflow [1]_ is a good way to approach issue triaging:


.. [1] Adapted from the pandas project `maintainers guide
<https://dev.pandas.io/docs/development/maintaining.html>`_ and
<https://pandas.pydata.org/docs/development/maintaining.html>`_ and
`the scikit-learn project
<https://scikit-learn.org/dev/developers/bug_triaging.html>`_ .

Expand Down
67 changes: 55 additions & 12 deletions doc/sphinxext/custom_roles.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,57 @@
from urllib.parse import urlsplit, urlunsplit

from docutils import nodes
from os.path import sep

from matplotlib import rcParamsDefault


def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
rendered = nodes.Text(f'rcParams["{text}"]')
class QueryReference(nodes.Inline, nodes.TextElement):
"""
Wraps a reference or pending reference to add a query string.

The query string is generated from the attributes added to this node.

Also equivalent to a `~docutils.nodes.literal` node.
"""

def to_query_string(self):
"""Generate query string from node attributes."""
return '&'.join(f'{name}={value}' for name, value in self.attlist())


def visit_query_reference_node(self, node):
"""
Resolve *node* into query strings on its ``reference`` children.

source = inliner.document.attributes['source'].replace(sep, '/')
rel_source = source.split('/doc/', 1)[1]
Then act as if this is a `~docutils.nodes.literal`.
"""
query = node.to_query_string()
for refnode in node.findall(nodes.reference):
uri = urlsplit(refnode['refuri'])._replace(query=query)
refnode['refuri'] = urlunsplit(uri)

levels = rel_source.count('/')
refuri = ('../' * levels +
'tutorials/introductory/customizing.html' +
f"?highlight={text}#a-sample-matplotlibrc-file")
self.visit_literal(node)


def depart_query_reference_node(self, node):
"""
Act as if this is a `~docutils.nodes.literal`.
"""
self.depart_literal(node)


def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
# Generate a pending cross-reference so that Sphinx will ensure this link
# isn't broken at some point in the future.
title = f'rcParam["{text}"]'
target = 'matplotlibrc-sample'
ref_nodes, messages = inliner.interpreted(title, f'{title} <{target}>',
'ref', lineno)

qr = QueryReference(rawtext, highlight=text)
qr += ref_nodes
node_list = [qr]

ref = nodes.reference(rawtext, rendered, refuri=refuri)
node_list = [nodes.literal('', '', ref)]
# The default backend would be printed as "agg", but that's not correct (as
# the default is actually determined by fallback).
if text in rcParamsDefault and text != "backend":
Expand All @@ -24,9 +60,16 @@ def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
nodes.literal('', repr(rcParamsDefault[text])),
nodes.Text(')'),
])
return node_list, []

return node_list, messages


def setup(app):
app.add_role("rc", rcparam_role)
app.add_node(
QueryReference,
html=(visit_query_reference_node, depart_query_reference_node),
latex=(visit_query_reference_node, depart_query_reference_node),
text=(visit_query_reference_node, depart_query_reference_node),
)
return {"parallel_read_safe": True, "parallel_write_safe": True}
4 changes: 3 additions & 1 deletion doc/sphinxext/redirect_from.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
This creates in the build directory a file ``build/html/topic/old-page.html``
that contains a relative refresh::

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0; url=new-page.html">
Expand All @@ -38,7 +39,8 @@
logger = logging.getLogger(__name__)


HTML_TEMPLATE = """<html>
HTML_TEMPLATE = """<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="0; url={v}">
</head>
Expand Down
3 changes: 2 additions & 1 deletion doc/users/faq/troubleshooting_faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,8 @@ Getting help
There are a number of good resources for getting help with Matplotlib.
There is a good chance your question has already been asked:

- The `mailing list archive <http://matplotlib.1069221.n5.nabble.com/>`_.
- The `mailing list archive
<https://discourse.matplotlib.org/c/community/matplotlib-users/6>`_.

- `GitHub issues <https://github.com/matplotlib/matplotlib/issues>`_.

Expand Down
3 changes: 1 addition & 2 deletions doc/users/prev_whats_new/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@ List of changes to Matplotlib prior to 2015
===========================================

This is a list of the changes made to Matplotlib from 2003 to 2015. For more
recent changes, please refer to the `what's new <../whats_new.html>`_ or
the `API changes <../../api/api_changes.html>`_.
recent changes, please refer to the :doc:`/users/release_notes`.

2015-11-16
Levels passed to contour(f) and tricontour(f) must be in increasing order.
Expand Down
2 changes: 1 addition & 1 deletion examples/images_contours_and_fields/shading_example.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
`Generic Mapping Tools`_.

.. _Mathematica: http://reference.wolfram.com/mathematica/ref/ReliefPlot.html
.. _Generic Mapping Tools: https://gmt.soest.hawaii.edu/
.. _Generic Mapping Tools: https://www.generic-mapping-tools.org/
"""

import numpy as np
Expand Down
2 changes: 1 addition & 1 deletion examples/user_interfaces/web_application_server_sgskip.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ def hello():
#############################################################################
#
# Since the above code is a Flask application, it should be run using the
# `flask command-line tool <https://flask.palletsprojects.com/en/master/cli/>`_
# `flask command-line tool <https://flask.palletsprojects.com/en/latest/cli/>`_
# Assuming that the working directory contains this script:
#
# Unix-like systems
Expand Down