Skip to content

Commit 016c2a7

Browse files
story645story645
committed
rstcheck config and precommit & fixed rst linting errors
1 parent 221f6c2 commit 016c2a7

27 files changed

+212
-83
lines changed

‎.pre-commit-config.yaml

+6-2
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@ repos:
2626
- id: no-commit-to-branch #default is master and main
2727
- id: trailing-whitespace
2828
exclude_types: [svg]
29-
3029
- repo: https://github.com/pycqa/flake8
3130
rev: 6.0.0
3231
hooks:
@@ -44,10 +43,15 @@ repos:
4443
"--skip",
4544
"doc/users/project/credits.rst"
4645
]
47-
4846
- repo: https://github.com/pycqa/isort
4947
rev: 5.12.0
5048
hooks:
5149
- id: isort
5250
name: isort (python)
5351
files: ^galleries/tutorials/|^galleries/examples/|^galleries/plot_types/
52+
- repo: https://github.com/rstcheck/rstcheck
53+
rev: v6.2.0
54+
hooks:
55+
- id: rstcheck
56+
additional_dependencies:
57+
- sphinx>=1.8.1

‎doc/_templates/autofunctions.rst

+2
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,9 @@ Functions
1414
.. autosummary::
1515
:template: autosummary.rst
1616
:toctree:
17+
1718
{% for item in functions %}{% if item not in ['plotting', 'colormaps'] %}
1819
{{ item }}{% endif %}{% endfor %}
20+
1921
{% endif %}
2022
{% endblock %}

‎doc/_templates/automodule.rst

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
{{ fullname | escape | underline}}
22

33
{% if fullname in ['mpl_toolkits.axes_grid1.colorbar'] %}
4-
.. To prevent problems with the autosummary for the colorbar doc
5-
treat this separately (sphinx-doc/sphinx/issues/4874)
4+
5+
.. To prevent problems with the autosummary for the colorbar doc treat this
6+
separately (sphinx-doc/sphinx/issues/4874)
7+
68
.. automodule:: {{ fullname }}
79
:members:
810

@@ -21,8 +23,10 @@ Classes
2123
.. autosummary::
2224
:template: autosummary.rst
2325
:toctree:
26+
2427
{% for item in classes %}{% if item not in ['zip', 'map', 'reduce'] %}
2528
{{ item }}{% endif %}{% endfor %}
29+
2630
{% endif %}
2731
{% endblock %}
2832

@@ -38,6 +42,7 @@ Functions
3842

3943
{% for item in functions %}{% if item not in ['zip', 'map', 'reduce'] %}
4044
{{ item }}{% endif %}{% endfor %}
45+
4146
{% endif %}
4247
{% endblock %}
4348
{% endif %}

‎doc/_templates/autosummary.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66

77
{% if objtype in ['class'] %}
8+
89
.. auto{{ objtype }}:: {{ objname }}
910
:show-inheritance:
1011
:special-members: __call__
@@ -16,11 +17,13 @@
1617

1718
{% if objtype in ['class', 'method', 'function'] %}
1819
{% if objname in ['AxesGrid', 'Scalable', 'HostAxes', 'FloatingAxes',
19-
'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}
20+
'ParasiteAxesAuxTrans', 'ParasiteAxes'] %}
21+
2022
.. Filter out the above aliases to other classes, as sphinx gallery
2123
creates no example file for those (sphinx-gallery/sphinx-gallery#365)
2224
2325
{% else %}
26+
2427
.. minigallery:: {{module}}.{{objname}}
2528
:add-heading:
2629

‎doc/_templates/autosummary_class_only.rst

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66

77
{% if objtype in ['class'] %}
8+
89
.. auto{{ objtype }}:: {{ objname }}
910
:no-members:
1011

‎doc/api/next_api_changes/behavior/25775-HZ.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Default antialiasing behavior changes for ``Text`` and ``Annotation``
44
``matplotlib.pyplot.annotate()`` and ``matplotlib.pyplot.text()`` now support parameter *antialiased* when initializing.
55
Examples:
66

7-
.. code-block::
7+
.. code-block:: python
88
99
mpl.text.Text(.5, .5, "foo\nbar", antialiased=True)
1010
plt.text(0.5, 0.5, '6 inches x 2 inches', antialiased=True)

‎doc/api/prev_api_changes/api_changes_2.1.2.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ didn't handle linewidths or linestyles etc.
1313

1414
This logic did not exist in `.axes.Axes.legend`. It was included (erroneously)
1515
in Matplotlib 2.1.1 when the legend argument parsing was unified
16-
[#9324](https://github.com/matplotlib/matplotlib/pull/9324). This change
16+
`#9324 <https://github.com/matplotlib/matplotlib/pull/9324>`_. This change
1717
removes that check in `.axes.Axes.legend` again to restore the old behavior.
1818

1919
This logic has also been dropped from `.Figure.legend`, where it

‎doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ consistently exposes all the attributes and methods related to the line marker
132132
(:ghissue:`11358`). This makes it easy to change the marker features after
133133
instantiating a legend.
134134

135-
.. code::
135+
.. code-block:: python
136136
137137
import matplotlib.pyplot as plt
138138
@@ -147,7 +147,7 @@ instantiating a legend.
147147
The former legend handler for Line2D objects has been renamed
148148
`.HandlerLine2DCompound`. To revert to the previous behaviour, one can use
149149

150-
.. code::
150+
.. code-block:: python
151151
152152
import matplotlib.legend as mlegend
153153
from matplotlib.legend_handler import HandlerLine2DCompound

‎doc/api/prev_api_changes/api_changes_3.7.0/behaviour.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Now, the halfrange remains fixed when vcenter is changed, and **vmin** and
5151

5252
For example, this is what the values were when changing vcenter previously.
5353

54-
.. code-block::
54+
.. code-block:: python
5555
5656
norm = CenteredNorm(vcenter=0, halfrange=1)
5757
# Move vcenter up by one
@@ -61,7 +61,7 @@ For example, this is what the values were when changing vcenter previously.
6161
6262
and now, with that same example
6363

64-
.. code-block::
64+
.. code-block:: python
6565
6666
norm = CenteredNorm(vcenter=0, halfrange=1)
6767
norm.vcenter = 1

‎doc/devel/MEP/MEP23.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ most use cases.
3535

3636
Sometimes when there are too many figures open at the same time, it is
3737
desirable to be able to group these under the same window
38-
[see](https://github.com/matplotlib/matplotlib/issues/2194).
38+
`see <https://github.com/matplotlib/matplotlib/issues/2194>`_.
3939

4040
The proposed solution modifies `.FigureManagerBase` to contain and manage more
4141
than one ``Canvas``. The settings parameter :rc:`backend.multifigure` control
@@ -44,7 +44,7 @@ when the **MultiFigure** behaviour is desired.
4444
**Note**
4545

4646
It is important to note, that the proposed solution, assumes that the
47-
[MEP22](https://github.com/matplotlib/matplotlib/wiki/Mep22) is
47+
`MEP22 <https://github.com/matplotlib/matplotlib/wiki/Mep22>`_. is
4848
already in place. This is simply because the actual implementation of
4949
the ``Toolbar`` makes it pretty hard to switch between canvases.
5050

‎doc/devel/MEP/MEP28.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ value of ``statfxn`` would be ``cbook.boxplot_stats``, but users could
264264
pass their own function. Then ``transform_in`` and ``transform_out`` would
265265
then be passed as elements of the ``statfxn_args`` parameter.
266266

267-
.. code:: python
267+
.. code:: none
268268
269269
def boxplot_stats(data, ..., transform_in=None, transform_out=None):
270270
if transform_in is None:

‎doc/devel/contribute.rst

+37-32
Original file line numberDiff line numberDiff line change
@@ -170,18 +170,18 @@ also welcome to post feature requests or pull requests.
170170

171171
If you are reporting a bug, please do your best to include the following:
172172

173-
1. A short, top-level summary of the bug. In most cases, this should be 1-2
173+
#. A short, top-level summary of the bug. In most cases, this should be 1-2
174174
sentences.
175175

176-
2. A short, self-contained code snippet to reproduce the bug, ideally allowing
176+
#. A short, self-contained code snippet to reproduce the bug, ideally allowing
177177
a simple copy and paste to reproduce. Please do your best to reduce the code
178178
snippet to the minimum required.
179179

180-
3. The actual outcome of the code snippet.
180+
#. The actual outcome of the code snippet.
181181

182-
4. The expected outcome of the code snippet.
182+
#. The expected outcome of the code snippet.
183183

184-
5. The Matplotlib version, Python version and platform that you are using. You
184+
#. The Matplotlib version, Python version and platform that you are using. You
185185
can grab the version with the following commands::
186186

187187
>>> import matplotlib
@@ -229,52 +229,54 @@ contribute to Matplotlib.
229229

230230
A brief overview of the workflow is as follows.
231231

232-
1. `Create an account <https://github.com/join>`_ on GitHub if you do not
232+
#. `Create an account <https://github.com/join>`_ on GitHub if you do not
233233
already have one.
234234

235-
2. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_:
236-
click on the 'Fork' button near the top of the page. This creates a copy of
237-
the code under your account on the GitHub server.
235+
#. Fork the `project repository <https://github.com/matplotlib/matplotlib>`_ by
236+
clicking on the :octicon:`repo-forked` **Fork** button near the top of the page.
237+
This creates a copy of the code under your account on the GitHub server.
238238

239-
.. tab-set::
239+
#. Set up a development environment:
240240

241-
.. tab-item:: Local development
241+
.. tab-set::
242242

243-
3. Clone this copy to your local disk::
243+
.. tab-item:: Local development
244244

245-
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
245+
Clone this copy to your local disk::
246246

247-
.. tab-item:: Using GitHub Codespaces
247+
git clone https://github.com/<YOUR GITHUB USERNAME>/matplotlib.git
248248

249-
3. Check out the Matplotlib repository and activate your development
250-
environment:
249+
.. tab-item:: Using GitHub Codespaces
251250

252-
* Open codespaces on your fork by clicking on the green "Code" button
251+
Check out the Matplotlib repository and activate your development environment:
252+
253+
#. Open codespaces on your fork by clicking on the green "Code" button
253254
on the GitHub web interface and selecting the "Codespaces" tab.
254-
* Next, click on "Open codespaces on <your branch name>". You will be
255+
256+
#. Next, click on "Open codespaces on <your branch name>". You will be
255257
able to change branches later, so you can select the default
256258
``main`` branch.
257-
* After the codespace is created, you will be taken to a new browser
259+
260+
#. After the codespace is created, you will be taken to a new browser
258261
tab where you can use the terminal to activate a pre-defined conda
259262
environment called ``mpl-dev``::
260263

261-
conda activate mpl-dev
262-
264+
conda activate mpl-dev
263265

264266

265-
4. Install the local version of Matplotlib with::
267+
#. Install the local version of Matplotlib with::
266268

267269
python -m pip install -e .
268270

269271
See :ref:`installing_for_devs` for detailed instructions.
270272

271-
5. Create a branch to hold your changes::
273+
#. Create a branch to hold your changes::
272274

273275
git checkout -b my-feature origin/main
274276

275277
and start making changes. Never work in the ``main`` branch!
276278

277-
6. Work on this task using Git to do the version control. Codespaces persist for
279+
#. Work on this task using Git to do the version control. Codespaces persist for
278280
some time (check the `documentation for details
279281
<https://docs.github.com/codespaces/getting-started/the-codespace-lifecycle>`_)
280282
and can be managed on https://github.com/codespaces. When you're done editing
@@ -301,11 +303,11 @@ GitHub Codespaces workflows
301303
<https://github.com/devcontainers/features/tree/main/src/desktop-lite>`_.
302304
You can use it by connecting to this desktop via your web browser. To do this:
303305

304-
1. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
306+
#. Press ``F1`` or ``Ctrl/Cmd+Shift+P`` and select
305307
``Ports: Focus on Ports View`` in the VSCode session to bring it into
306308
focus. Open the ports view in your tool, select the ``noVNC`` port, and
307309
click the Globe icon.
308-
2. In the browser that appears, click the Connect button and enter the desktop
310+
#. In the browser that appears, click the Connect button and enter the desktop
309311
password (``vscode`` by default).
310312

311313
Check the `GitHub instructions
@@ -391,10 +393,11 @@ Rules
391393
Introducing
392394
~~~~~~~~~~~
393395

394-
1. Announce the deprecation in a new file
396+
#. Announce the deprecation in a new file
395397
:file:`doc/api/next_api_changes/deprecations/99999-ABC.rst` where ``99999``
396398
is the pull request number and ``ABC`` are the contributor's initials.
397-
2. If possible, issue a `~matplotlib.MatplotlibDeprecationWarning` when the
399+
400+
#. If possible, issue a `~matplotlib.MatplotlibDeprecationWarning` when the
398401
deprecated API is used. There are a number of helper tools for this:
399402

400403
- Use ``_api.warn_deprecated()`` for general deprecation warnings
@@ -411,7 +414,7 @@ Introducing
411414

412415
You can use standard rst cross references in *alternative*.
413416

414-
3. Make appropriate changes to the type hints in the associated ``.pyi`` file.
417+
#. Make appropriate changes to the type hints in the associated ``.pyi`` file.
415418
The general guideline is to match runtime reported behavior.
416419

417420
- Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
@@ -431,15 +434,17 @@ Introducing
431434
Expiring
432435
~~~~~~~~
433436

434-
1. Announce the API changes in a new file
437+
#. Announce the API changes in a new file
435438
:file:`doc/api/next_api_changes/[kind]/99999-ABC.rst` where ``99999``
436439
is the pull request number and ``ABC`` are the contributor's initials, and
437440
``[kind]`` is one of the folders :file:`behavior`, :file:`development`,
438441
:file:`removals`. See :file:`doc/api/next_api_changes/README.rst` for more
439442
information. For the content, you can usually copy the deprecation notice
440443
and adapt it slightly.
441-
2. Change the code functionality and remove any related deprecation warnings.
442-
3. Make appropriate changes to the type hints in the associated ``.pyi`` file.
444+
445+
#. Change the code functionality and remove any related deprecation warnings.
446+
447+
#. Make appropriate changes to the type hints in the associated ``.pyi`` file.
443448

444449
- Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
445450
are to be removed on expiry.

‎doc/devel/document.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -668,7 +668,7 @@ in that case, they can be documented as an ``.. ACCEPTS:`` block, e.g. for
668668

669669
.. code-block:: python
670670
671-
def set_xlim(self, ...):
671+
def set_xlim(self, left=None, right=None):
672672
"""
673673
Set the x-axis view limits.
674674

‎doc/users/next_whats_new/antialiasing_text_annotation.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ When *antialiased* is set to ``False``, antialiasing will not be applied to the
66
When *antialiased* is not specified, antialiasing will be set by :rc:`text.antialiased` at the creation time of ``Text`` and ``Annotation`` object.
77
Examples:
88

9-
.. code-block::
9+
.. code-block:: python
1010
1111
mpl.text.Text(.5, .5, "foo\nbar", antialiased=True)
1212
plt.text(0.5, 0.5, '6 inches x 2 inches', antialiased=True)
@@ -15,7 +15,7 @@ Examples:
1515
If the text contains math expression, *antialiased* applies to the whole text.
1616
Examples:
1717

18-
.. code-block::
18+
.. code-block:: python
1919
2020
# no part will be antialiased for the text below
2121
plt.text(0.5, 0.25, r"$I'm \sqrt{x}$", antialiased=False)

‎doc/users/next_whats_new/boldsym_mathtext.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Supports using the ``\boldsymbol{}`` command in mathtext:
66
To change symbols to bold enclose the text in a font command as
77
shown:
88

9-
.. code-block::
9+
.. code-block:: none
1010
1111
r'$\boldsymbol{a+2+\alpha}$'
1212

‎doc/users/next_whats_new/mathtext_features.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
To use it to enclose the math in a substack command as shown:
77

8-
.. code-block::
8+
.. code-block:: none
99
1010
r'$\sum_{\substack{1\leq i\leq 3\\ 1\leq j\leq 5}}$'
1111
@@ -23,7 +23,7 @@ The ``\middle`` delimiter has been added, and can now be used with the
2323
To use the middle command enclose it in between the ``\left`` and
2424
``\right`` delimiter command as shown:
2525

26-
.. code-block::
26+
.. code-block:: none
2727
2828
r'$\left( \frac{a}{b} \middle| q \right)$'
2929

0 commit comments

Comments
 (0)