Skip to content

Commit 944b99a

Browse files
tacaswelltacaswell
authored
Merge pull request matplotlib#23641 from QuLogic/fix-doc-bugs
Fix doc bugs found in 3.5.3
2 parents de50ba9 + e5df3de commit 944b99a

File tree

15 files changed

+118
-72
lines changed

15 files changed

+118
-72
lines changed

‎doc/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ def _check_dependencies():
153153
'python': ('https://docs.python.org/3/', None),
154154
'scipy': ('https://docs.scipy.org/doc/scipy/', None),
155155
'tornado': ('https://www.tornadoweb.org/en/stable/', None),
156-
'xarray': ('https://xarray.pydata.org/en/stable/', None),
156+
'xarray': ('https://docs.xarray.dev/en/stable/', None),
157157
}
158158

159159

‎doc/devel/MEP/MEP14.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,8 @@ number of other projects:
7878
- `Microsoft DirectWrite`_
7979
- `Apple Core Text`_
8080

81-
.. _pango: https://www.pango.org/
82-
.. _harfbuzz: https://www.freedesktop.org/wiki/Software/HarfBuzz/
81+
.. _pango: https://pango.gnome.org
82+
.. _harfbuzz: https://github.com/harfbuzz/harfbuzz
8383
.. _QtTextLayout: https://doc.qt.io/archives/qt-4.8/qtextlayout.html
8484
.. _Microsoft DirectWrite: https://docs.microsoft.com/en-ca/windows/win32/directwrite/introducing-directwrite
8585
.. _Apple Core Text: https://developer.apple.com/library/archive/documentation/StringsTextFonts/Conceptual/CoreText_Programming/Overview/Overview.html

‎doc/devel/MEP/MEP29.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ one has to look at the gallery where one such example is provided:
3434
This example takes a list of strings as well as a list of colors which makes it
3535
cumbersome to use. An alternative would be to use a restricted set of pango_-like markup and to interpret this markup.
3636

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

3939
Some markup examples::
4040

‎doc/devel/dependencies.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ Font handling and rendering
8585
* `LaTeX <https://www.latex-project.org/>`_ (with `cm-super
8686
<https://ctan.org/pkg/cm-super>`__ and `underscore
8787
<https://ctan.org/pkg/underscore>`__ ) and `GhostScript (>=9.0)
88-
<https://ghostscript.com/download/>`_ : for rendering text with LaTeX.
88+
<https://ghostscript.com/releases/>`_ : for rendering text with LaTeX.
8989
* `fontconfig <https://www.fontconfig.org>`_ (>= 2.7): for detection of system
9090
fonts on Linux.
9191

@@ -260,7 +260,7 @@ will be skipped by pytest.
260260
Inkscape to system PATH”, either for all users or current user, or the
261261
tests will not find it.
262262

263-
.. _Ghostscript: https://www.ghostscript.com/
263+
.. _Ghostscript: https://ghostscript.com/
264264
.. _Inkscape: https://inkscape.org
265265
.. _flake8: https://pypi.org/project/flake8/
266266
.. _nbconvert: https://pypi.org/project/nbconvert/

‎doc/devel/style_guide.rst

Lines changed: 47 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ reliability and consistency in documentation. They are not interchangeable.
2929
+------------------+--------------------------+--------------+--------------+
3030
| Term | Description | Correct | Incorrect |
3131
+==================+==========================+==============+==============+
32-
| Figure_ | Matplotlib working space | - *For | - "The figure|
32+
| |Figure| | Matplotlib working space | - *For | - "The figure|
3333
| | for programming. | Matplotlib | is the |
3434
| | | objects*: | working |
3535
| | | Figure, | space for |
@@ -39,11 +39,11 @@ reliability and consistency in documentation. They are not interchangeable.
3939
| | | space for | provide the|
4040
| | | the visual.| visuals." |
4141
| | | - *Referring | - "The |
42-
| | | to class*: | Figure_ |
43-
| | | Figure_ , | Four |
42+
| | | to class*: | |Figure| |
43+
| | | |Figure|, | Four |
4444
| | | "Methods | leglock is |
4545
| | | within the | a wrestling|
46-
| | | Figure_ | move." |
46+
| | | |Figure| | move." |
4747
| | | provide the| |
4848
| | | visuals." | |
4949
| | | - *General | |
@@ -55,28 +55,29 @@ reliability and consistency in documentation. They are not interchangeable.
5555
| | | figure | |
5656
| | | skater." | |
5757
+------------------+--------------------------+--------------+--------------+
58-
| Axes_ | Subplots within Figure. | - *For | - "The axes |
58+
| |Axes| | Subplots within Figure. | - *For | - "The axes |
5959
| | Contains plot elements | Matplotlib | methods |
6060
| | and is responsible for | objects*: | transform |
6161
| | plotting and configuring | Axes, "An | the data." |
62-
| | additional details. | Axes is a | - "Each Axes_|
63-
| | | subplot | is specific|
64-
| | | within the | to a |
65-
| | | Figure." | Figure." |
62+
| | additional details. | Axes is a | - "Each |
63+
| | | subplot | |Axes| is |
64+
| | | within the | specific to|
65+
| | | Figure." | a Figure." |
6666
| | | - *Referring | - "The |
6767
| | | to class*: | musicians |
68-
| | | Axes_ , | on stage |
69-
| | | "Each Axes_| call their |
70-
| | | is specific| guitars |
71-
| | | to one | Axes." |
72-
| | | Figure." | - "The point |
73-
| | | - *General | where the |
74-
| | | language*: | Axes meet |
75-
| | | axes, "Both| is the |
76-
| | | loggers and| origin of |
77-
| | | lumberjacks| the |
78-
| | | use axes to| coordinate |
79-
| | | chop wood."| system." |
68+
| | | |Axes|, | on stage |
69+
| | | "Each | call their |
70+
| | | |Axes| is | guitars |
71+
| | | specific to| Axes." |
72+
| | | one | - "The point |
73+
| | | Figure." | where the |
74+
| | | - *General | Axes meet |
75+
| | | language*: | is the |
76+
| | | axes, "Both| origin of |
77+
| | | loggers and| the |
78+
| | | lumberjacks| coordinate |
79+
| | | use axes to| system." |
80+
| | | chop wood."| |
8081
| | | OR "There | |
8182
| | | are no | |
8283
| | | standard | |
@@ -89,24 +90,25 @@ reliability and consistency in documentation. They are not interchangeable.
8990
| | | (Plural of | |
9091
| | | axis) | |
9192
+------------------+--------------------------+--------------+--------------+
92-
| Artist_ | Broad variety of | - *For | - "Configure |
93+
| |Artist| | Broad variety of | - *For | - "Configure |
9394
| | Matplotlib objects that | Matplotlib | the legend |
9495
| | display visuals. | objects*: | artist with|
9596
| | | Artist, | its |
9697
| | | "Artists | respective |
9798
| | | display | method." |
9899
| | | visuals and| - "There is |
99-
| | | are the | an Artist_ |
100-
| | | visible | for that |
101-
| | | elements | visual in |
102-
| | | when the | the graph."|
103-
| | | rendering | - "Some |
104-
| | | a Figure." | Artists |
105-
| | | - *Referring | became |
106-
| | | to class*: | famous only|
107-
| | | Artist_ , | by |
108-
| | | "Each | accident." |
109-
| | | Artist_ has| |
100+
| | | are the | an |
101+
| | | visible | |Artist| |
102+
| | | elements | for that |
103+
| | | when | visual in |
104+
| | | rendering a| the graph."|
105+
| | | Figure." | - "Some |
106+
| | | - *Referring | Artists |
107+
| | | to class*: | became |
108+
| | | |Artist| , | famous only|
109+
| | | "Each | by |
110+
| | | |Artist| | accident." |
111+
| | | has | |
110112
| | | respective | |
111113
| | | methods and| |
112114
| | | functions."| |
@@ -119,7 +121,7 @@ reliability and consistency in documentation. They are not interchangeable.
119121
| | | is from | |
120122
| | | France." | |
121123
+------------------+--------------------------+--------------+--------------+
122-
| Axis_ | Human-readable single | - *For | - "Plot the |
124+
| |Axis| | Human-readable single | - *For | - "Plot the |
123125
| | dimensional object | Matplotlib | graph onto |
124126
| | of reference marks | objects*: | the axis." |
125127
| | containing ticks, tick | Axis, "The | - "Each Axis |
@@ -133,12 +135,13 @@ reliability and consistency in documentation. They are not interchangeable.
133135
| | | objects) | - "In some |
134136
| | | - *Referring | computer |
135137
| | | to class*: | graphics |
136-
| | | Axis_ , | contexts, |
137-
| | | "The Axis_ | the |
138-
| | | contains | ordinate |
139-
| | | respective | Axis_ may |
140-
| | | XAxis and | be oriented|
141-
| | | YAxis | downwards."|
138+
| | | |Axis|, | contexts, |
139+
| | | "The | the |
140+
| | | |Axis| | ordinate |
141+
| | | contains | |Axis| may |
142+
| | | respective | be oriented|
143+
| | | XAxis and | downwards."|
144+
| | | YAxis | |
142145
| | | objects." | |
143146
| | | - *General | |
144147
| | | language*: | |
@@ -162,10 +165,10 @@ reliability and consistency in documentation. They are not interchangeable.
162165
| | | | interface |
163166
+------------------+--------------------------+--------------+--------------+
164167

165-
.. _Figure: :class:`~matplotlib.figure.Figure`
166-
.. _Axes: :class:`~matplotlib.axes.Axes`
167-
.. _Artist: :class:`~matplotlib.artist.Artist`
168-
.. _Axis: :class:`matplotlib.axis.Axis`
168+
.. |Figure| replace:: :class:`~matplotlib.figure.Figure`
169+
.. |Axes| replace:: :class:`~matplotlib.axes.Axes`
170+
.. |Artist| replace:: :class:`~matplotlib.artist.Artist`
171+
.. |Axis| replace:: :class:`~matplotlib.axis.Axis`
169172

170173

171174
Grammar

‎doc/devel/triage.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ The following workflow [1]_ is a good way to approach issue triaging:
208208

209209

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

‎doc/sphinxext/custom_roles.py

Lines changed: 55 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,57 @@
1+
from urllib.parse import urlsplit, urlunsplit
2+
13
from docutils import nodes
2-
from os.path import sep
4+
35
from matplotlib import rcParamsDefault
46

57

6-
def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
7-
rendered = nodes.Text(f'rcParams["{text}"]')
8+
class QueryReference(nodes.Inline, nodes.TextElement):
9+
"""
10+
Wraps a reference or pending reference to add a query string.
11+
12+
The query string is generated from the attributes added to this node.
13+
14+
Also equivalent to a `~docutils.nodes.literal` node.
15+
"""
16+
17+
def to_query_string(self):
18+
"""Generate query string from node attributes."""
19+
return '&'.join(f'{name}={value}' for name, value in self.attlist())
20+
21+
22+
def visit_query_reference_node(self, node):
23+
"""
24+
Resolve *node* into query strings on its ``reference`` children.
825
9-
source = inliner.document.attributes['source'].replace(sep, '/')
10-
rel_source = source.split('/doc/', 1)[1]
26+
Then act as if this is a `~docutils.nodes.literal`.
27+
"""
28+
query = node.to_query_string()
29+
for refnode in node.findall(nodes.reference):
30+
uri = urlsplit(refnode['refuri'])._replace(query=query)
31+
refnode['refuri'] = urlunsplit(uri)
1132

12-
levels = rel_source.count('/')
13-
refuri = ('../' * levels +
14-
'tutorials/introductory/customizing.html' +
15-
f"?highlight={text}#a-sample-matplotlibrc-file")
33+
self.visit_literal(node)
34+
35+
36+
def depart_query_reference_node(self, node):
37+
"""
38+
Act as if this is a `~docutils.nodes.literal`.
39+
"""
40+
self.depart_literal(node)
41+
42+
43+
def rcparam_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
44+
# Generate a pending cross-reference so that Sphinx will ensure this link
45+
# isn't broken at some point in the future.
46+
title = f'rcParam["{text}"]'
47+
target = 'matplotlibrc-sample'
48+
ref_nodes, messages = inliner.interpreted(title, f'{title} <{target}>',
49+
'ref', lineno)
50+
51+
qr = QueryReference(rawtext, highlight=text)
52+
qr += ref_nodes
53+
node_list = [qr]
1654

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

2966

3067
def setup(app):
3168
app.add_role("rc", rcparam_role)
69+
app.add_node(
70+
QueryReference,
71+
html=(visit_query_reference_node, depart_query_reference_node),
72+
latex=(visit_query_reference_node, depart_query_reference_node),
73+
text=(visit_query_reference_node, depart_query_reference_node),
74+
)
3275
return {"parallel_read_safe": True, "parallel_write_safe": True}

‎doc/sphinxext/redirect_from.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
This creates in the build directory a file ``build/html/topic/old-page.html``
1616
that contains a relative refresh::
1717
18+
<!DOCTYPE html>
1819
<html>
1920
<head>
2021
<meta charset="utf-8">
@@ -39,7 +40,7 @@
3940
logger = logging.getLogger(__name__)
4041

4142

42-
HTML_TEMPLATE = """\
43+
HTML_TEMPLATE = """<!DOCTYPE html>
4344
<html>
4445
<head>
4546
<meta charset="utf-8">

‎doc/users/faq/troubleshooting_faq.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,8 @@ Getting help
8484
There are a number of good resources for getting help with Matplotlib.
8585
There is a good chance your question has already been asked:
8686

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

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

‎doc/users/prev_whats_new/changelog.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@ List of changes to Matplotlib prior to 2015
44
===========================================
55

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

109
2015-11-16
1110
Levels passed to contour(f) and tricontour(f) must be in increasing order.

0 commit comments

Comments
 (0)