Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b5c141c

Browse files
jklymakjklymak
authored
DOC: user/explain reorg (and moving a lot of tutorials). (#25395)
* DOC: make users/explain a sphinx gallery [ci doc] This is a major re-org whereby much of galleries/tutorials is moved to galleries/user_explain, and hence users/explain in the published docs. Much of this may be rearranged more over the 3.8 cycle. Additionally most tutorial references were moved from hard :doc: references to soft :ref: references for ease of further rearrangement. Note this uses the git head of sphinx-gallery and mpl-sphinx-theme. We should watch the release cycle of sphinx-gallery so that it can be changed to one of their releases.
1 parent a7ba07c commit b5c141c

File tree

137 files changed

+1145
-456
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

137 files changed

+1145
-456
lines changed

‎.circleci/config.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,12 @@ commands:
9797
- run:
9898
name: Install Python dependencies
9999
command: |
100+
# remove when sphinx-gallery releases #1071:
100101
python -m pip install --user \
101102
numpy<< parameters.numpy_version >> codecov coverage \
102103
-r requirements/doc/doc-requirements.txt
104+
python -m pip install --no-deps --user \
105+
git+https://github.com/sphinx-gallery/sphinx-gallery.git
103106
python -m pip install --no-deps --user \
104107
git+https://github.com/matplotlib/mpl-sphinx-theme.git
105108

‎.flake8

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -55,22 +55,22 @@ per-file-ignores =
5555
lib/pylab.py: F401, F403
5656

5757
doc/conf.py: E402
58-
galleries/tutorials/advanced/path_tutorial.py: E402
59-
galleries/tutorials/advanced/patheffects_guide.py: E402
60-
galleries/tutorials/advanced/transforms_tutorial.py: E402, E501
61-
galleries/tutorials/colors/colormaps.py: E501
62-
galleries/tutorials/colors/colors.py: E402
63-
galleries/tutorials/intermediate/artists.py: E402
64-
galleries/tutorials/intermediate/constrainedlayout_guide.py: E402
65-
galleries/tutorials/intermediate/legend_guide.py: E402
66-
galleries/tutorials/intermediate/tight_layout_guide.py: E402
67-
galleries/tutorials/introductory/animation_tutorial.py: E501
68-
galleries/tutorials/introductory/images.py: E501
69-
galleries/tutorials/introductory/pyplot.py: E402, E501
70-
galleries/tutorials/text/annotations.py: E402, E501
71-
galleries/tutorials/text/mathtext.py: E501
72-
galleries/tutorials/text/text_intro.py: E402
73-
galleries/tutorials/text/text_props.py: E501
58+
galleries/users_explain/artists/paths.py: E402
59+
galleries/users_explain/artists/patheffects_guide.py: E402
60+
galleries/users_explain/artists/transforms_tutorial.py: E402, E501
61+
galleries/users_explain/colors/colormaps.py: E501
62+
galleries/users_explain/colors/colors.py: E402
63+
galleries/tutorials/artists.py: E402
64+
galleries/users_explain/axes/constrainedlayout_guide.py: E402
65+
galleries/users_explain/axes/legend_guide.py: E402
66+
galleries/users_explain/axes/tight_layout_guide.py: E402
67+
galleries/users_explain/animations/animations.py: E501
68+
galleries/tutorials/images.py: E501
69+
galleries/tutorials/pyplot.py: E402, E501
70+
galleries/users_explain/text/annotations.py: E402, E501
71+
galleries/users_explain/text/mathtext.py: E501
72+
galleries/users_explain/text/text_intro.py: E402
73+
galleries/users_explain/text/text_props.py: E501
7474

7575
galleries/examples/animation/frame_grabbing_sgskip.py: E402
7676
galleries/examples/images_contours_and_fields/tricontour_demo.py: E201

‎doc/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ clean:
2222
rm -rf "$(SOURCEDIR)/gallery"
2323
rm -rf "$(SOURCEDIR)/plot_types"
2424
rm -rf "$(SOURCEDIR)/tutorials"
25+
rm -rf "$(SOURCEDIR)/users/explain"
2526
rm -rf "$(SOURCEDIR)/savefig"
2627
rm -rf "$(SOURCEDIR)/sphinxext/__pycache__"
2728
rm -f $(SOURCEDIR)/_static/constrained_layout*.png

‎doc/api/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ programmatic plot generation.
7575
Further reading:
7676

7777
- The `matplotlib.pyplot` function reference
78-
- :doc:`/tutorials/introductory/pyplot`
78+
- :ref:`pyplot_tutorial`
7979
- :ref:`Pyplot examples <pyplots_examples>`
8080

8181
.. _api-index:

‎doc/api/prev_api_changes/api_changes_1.4.x.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ original location:
8888
* The legend handler interface has changed from a callable, to any object
8989
which implements the ``legend_artists`` method (a deprecation phase will
9090
see this interface be maintained for v1.4). See
91-
:doc:`/tutorials/intermediate/legend_guide` for further details. Further legend changes
91+
:ref:`legend_guide` for further details. Further legend changes
9292
include:
9393

9494
* ``matplotlib.axes.Axes._get_legend_handles`` now returns a generator of

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ New dependency
99

1010
`kiwisolver <https://github.com/nucleic/kiwi>`__ is now a required
1111
dependency to support the new constrained_layout, see
12-
:doc:`/tutorials/intermediate/constrainedlayout_guide` for
12+
:ref:`constrainedlayout_guide` for
1313
more details.
1414

1515

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ library, so using it should be safe, but layouts may not be exactly the same as
2424
more development takes place.
2525

2626
Details of using ``constrained_layout``, and its algorithm are available at
27-
:doc:`/tutorials/intermediate/constrainedlayout_guide`
27+
:ref:`constrainedlayout_guide`
2828

2929
``plt.subplot`` re-selection without keyword arguments
3030
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎doc/api/style_api.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Styles are predefined sets of `.rcParams` that define the visual appearance of
66
a plot.
77

8-
:doc:`/tutorials/introductory/customizing` describes the mechanism and usage
8+
:ref:`customizing` describes the mechanism and usage
99
of styles.
1010

1111
The :doc:`/gallery/style_sheets/style_sheets_reference` gives an overview of

‎doc/api/toolkits/mplot3d.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ and feel as regular 2D plots. Not the fastest or most feature complete 3D
1212
library out there, but it ships with Matplotlib and thus may be a lighter
1313
weight solution for some use cases.
1414

15-
See the :doc:`mplot3d tutorial </tutorials/toolkits/mplot3d>` for
15+
See the :ref:`mplot3d tutorial <mplot3d>` for
1616
more information.
1717

1818
.. image:: /_static/demo_mplot3d.png

‎doc/conf.py

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -213,11 +213,14 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
213213
gallery_conf['image_srcset'] = []
214214
return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs)
215215

216-
gallery_dirs = [f'{ed}' for ed in ['gallery', 'tutorials', 'plot_types']
216+
gallery_dirs = [f'{ed}' for ed in
217+
['gallery', 'tutorials', 'plot_types', 'users/explain']
217218
if f'{ed}/*' not in skip_subdirs]
218219

219-
example_dirs = [f'../galleries/{gd}'.replace('gallery', 'examples')
220-
for gd in gallery_dirs]
220+
example_dirs = []
221+
for gd in gallery_dirs:
222+
gd = gd.replace('gallery', 'examples').replace('users/explain', 'users_explain')
223+
example_dirs += [f'../galleries/{gd}']
221224

222225
sphinx_gallery_conf = {
223226
'backreferences_dir': Path('api') / Path('_as_gen'),
@@ -244,6 +247,7 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
244247
'thumbnail_size': (320, 224),
245248
'within_subsection_order': gallery_order.subsectionorder,
246249
'capture_repr': (),
250+
'copyfile_regex': r'.*\.rst',
247251
}
248252

249253
if 'plot_gallery=0' in sys.argv:

‎doc/devel/MEP/MEP29.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ Improvements
5454
to use the html.parser from the standard library.
5555

5656
* Computation of text fragment positions could benefit from the OffsetFrom
57-
class. See for example item 5 in `Using Complex Coordinates with Annotations <https://matplotlib.org/devdocs/tutorials/text/annotations.html#using-complex-coordinates-with-annotations>`_
57+
class. See for example item 5 in `Using Complex Coordinates with Annotations <https://matplotlib.org/devdocs/users/explain/text/annotations.html#using-complex-coordinates-with-annotations>`_
5858

5959
Problems
6060
--------

‎doc/devel/documenting_mpl.rst

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -202,15 +202,15 @@ Documents can be linked with the ``:doc:`` directive:
202202
203203
See the :doc:`/users/installing/index`
204204
205-
See the tutorial :doc:`/tutorials/introductory/quick_start`
205+
See the tutorial :ref:`quick_start`
206206
207207
See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
208208
209209
will render as:
210210

211211
See the :doc:`/users/installing/index`
212212

213-
See the tutorial :doc:`/tutorials/introductory/quick_start`
213+
See the tutorial :ref:`quick_start`
214214

215215
See the example :doc:`/gallery/lines_bars_and_markers/simple_plot`
216216

@@ -858,10 +858,9 @@ The first comment block is treated as ReST_ text. The other comment blocks
858858
render as comments in :doc:`/gallery/lines_bars_and_markers/simple_plot`.
859859

860860
Tutorials are made with the exact same mechanism, except they are longer, and
861-
typically have more than one comment block (i.e.
862-
:doc:`/tutorials/introductory/quick_start`). The first comment block
863-
can be the same as the example above. Subsequent blocks of ReST text are
864-
delimited by the line ``# %%`` :
861+
typically have more than one comment block (i.e. :ref:`quick_start`). The
862+
first comment block can be the same as the example above. Subsequent blocks of
863+
ReST text are delimited by the line ``# %%`` :
865864

866865
.. code-block:: python
867866

‎doc/index.rst

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,9 @@ Learning resources
4949
Tutorials
5050
^^^
5151

52-
- :doc:`Quick-start guide <tutorials/introductory/quick_start>`
52+
- :ref:`Quick-start guide <quick_start>`
5353
- :doc:`Plot types <plot_types/index>`
54-
- :ref:`Introductory tutorials <tutorials-introductory>`
54+
- :ref:`users-guide-using`
5555
- :doc:`External learning resources <users/resources/index>`
5656

5757
.. grid-item-card::
@@ -69,11 +69,8 @@ Learning resources
6969
Understand how Matplotlib works
7070
^^^
7171

72-
- The :ref:`users-guide-explain` in the :doc:`Users guide
73-
<users/index>`
74-
- Many of the :ref:`Intermediate <tutorials-intermediate>` and
75-
:ref:`Advanced <tutorials-advanced>` tutorials have explanatory
76-
material
72+
- :ref:`users-guide-explain` in the :doc:`Users guide
73+
<users/index>` has a number of advanced topics.
7774

7875
.. grid-item-card::
7976
:padding: 2

‎doc/users/explain/index.rst

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎doc/users/faq/howto_faq.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ actually perform such a rendering and inspect the result.
9797
Find all objects in a figure of a certain type
9898
----------------------------------------------
9999

100-
Every Matplotlib artist (see :doc:`/tutorials/intermediate/artists`) has a method
100+
Every Matplotlib artist (see :ref:`artists_tutorial`) has a method
101101
called :meth:`~matplotlib.artist.Artist.findobj` that can be used to
102102
recursively search the artist for any artists it may contain that meet
103103
some criteria (e.g., match all :class:`~matplotlib.lines.Line2D`
@@ -183,8 +183,8 @@ multiple ways to fix this:
183183
`.pyplot.subplots_adjust`.
184184
- Use one of the automatic layout mechanisms:
185185

186-
- constrained layout (:doc:`/tutorials/intermediate/constrainedlayout_guide`)
187-
- tight layout (:doc:`/tutorials/intermediate/tight_layout_guide`)
186+
- constrained layout (:ref:`constrainedlayout_guide`)
187+
- tight layout (:ref:`tight_layout_guide`)
188188

189189
- Calculate good values from the size of the plot elements yourself
190190
(:doc:`/gallery/subplots_axes_and_figures/auto_subplots_adjust`)

‎doc/users/faq/troubleshooting_faq.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ provide the following information in your e-mail to the `mailing list
106106
GitHub, PyPI, or `Anaconda <https://www.anaconda.com/>`_).
107107

108108
* Any customizations to your ``matplotlibrc`` file (see
109-
:doc:`/tutorials/introductory/customizing`).
109+
:ref:`customizing`).
110110

111111
* If the problem is reproducible, please try to provide a *minimal*, standalone
112112
Python script that demonstrates the problem. This is *the* critical step.

‎doc/users/getting_started/index.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,5 +51,5 @@ Where to go next
5151

5252
- Check out :doc:`Plot types </plot_types/index>` to get an overview of the
5353
types of plots you can create with Matplotlib.
54-
- Learn Matplotlib from the ground up in the
55-
:doc:`Quick-start guide </tutorials/introductory/quick_start>`.
54+
- Learn Matplotlib from the ground up in the :ref:`Quick-start guide
55+
<quick_start>`.

‎doc/users/installing/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ example::
219219

220220
This will give you additional information about which backends Matplotlib is
221221
loading, version information, and more. At this point you might want to make
222-
sure you understand Matplotlib's :doc:`configuration </tutorials/introductory/customizing>`
222+
sure you understand Matplotlib's :ref:`configuration <customizing>`
223223
process, governed by the :file:`matplotlibrc` configuration file which contains
224224
instructions within and the concept of the Matplotlib backend.
225225

‎doc/users/prev_whats_new/dflt_style_changes.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ are only specified via hex values. To access these colors outside of
9898
the property cycling the notation for colors ``'CN'``, where ``N``
9999
takes values 0-9, was added to
100100
denote the first 10 colors in :rc:`axes.prop_cycle`. See
101-
:doc:`/tutorials/colors/colors` for more details.
101+
:ref:`colors_def` for more details.
102102

103103
To restore the old color cycle use
104104

@@ -147,7 +147,7 @@ watch Nathaniel Smith and Stéfan van der Walt's talk from SciPy2015.
147147
See `here for many more details <https://bids.github.io/colormap/>`__
148148
about the other alternatives and the tools used to create the color
149149
map. For details on all of the colormaps available in matplotlib see
150-
:doc:`/tutorials/colors/colormaps`.
150+
:ref:`colormaps`.
151151

152152
.. raw:: html
153153

‎doc/users/prev_whats_new/whats_new_0.99.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,11 @@ What's new in Matplotlib 0.99 (Aug 29, 2009)
1111
New documentation
1212
-----------------
1313

14-
Jae-Joon Lee has written two new guides :doc:`/tutorials/intermediate/legend_guide`
14+
Jae-Joon Lee has written two new guides :ref:`legend_guide`
1515
and :ref:`plotting-guide-annotation`. Michael Sarahan has written
16-
:doc:`/tutorials/introductory/images`. John Hunter has written two new tutorials on
17-
working with paths and transformations: :doc:`/tutorials/advanced/path_tutorial` and
18-
:doc:`/tutorials/advanced/transforms_tutorial`.
16+
:ref:`image_tutorial`. John Hunter has written two new tutorials on
17+
working with paths and transformations: :ref:`paths` and
18+
:ref:`transforms_tutorial`.
1919

2020
.. _whats-new-mplot3d:
2121

@@ -26,7 +26,7 @@ Reinier Heeres has ported John Porter's mplot3d over to the new
2626
matplotlib transformations framework, and it is now available as a
2727
toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl
2828
installs). See :ref:`mplot3d-examples-index` and
29-
:doc:`/tutorials/toolkits/mplot3d`.
29+
:ref:`mplot3d`.
3030

3131
.. plot::
3232

‎doc/users/prev_whats_new/whats_new_1.0.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Sophisticated subplot grid layout
2323

2424
Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for
2525
doing complex subplot layouts, featuring row and column spans and
26-
more. See :doc:`/tutorials/intermediate/arranging_axes` for a tutorial
26+
more. See :ref:`arranging_axes` for a tutorial
2727
overview.
2828

2929
.. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_001.png

‎doc/users/prev_whats_new/whats_new_1.1.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ The usage of this functionality can be as simple as ::
8585

8686
and it will adjust the spacing between subplots
8787
so that the axis labels do not overlap with neighboring subplots. A
88-
:doc:`/tutorials/intermediate/tight_layout_guide` has been created to show how to use
88+
:ref:`tight_layout_guide` has been created to show how to use
8989
this new tool.
9090

9191
PyQT4, PySide, and IPython
@@ -114,7 +114,7 @@ legends for complex plots such as :meth:`~matplotlib.pyplot.stem` plots
114114
will now display correctly. Second, the 'best' placement of a legend has
115115
been improved in the presence of NANs.
116116

117-
See the :doc:`/tutorials/intermediate/legend_guide` for more detailed explanation and
117+
See the :ref:`legend_guide` for more detailed explanation and
118118
examples.
119119

120120
.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_legend_demo_004.png
@@ -133,7 +133,7 @@ as 2D plotting, Ben Root has made several improvements to the
133133
improved to bring the class towards feature-parity with regular
134134
Axes objects
135135

136-
* Documentation for :doc:`/tutorials/toolkits/mplot3d` was significantly expanded
136+
* Documentation for :ref:`mplot3d` was significantly expanded
137137

138138
* Axis labels and orientation improved
139139

‎doc/users/prev_whats_new/whats_new_1.2.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ PGF/TikZ backend
3939
Peter Würtz wrote a backend that allows matplotlib to export figures as
4040
drawing commands for LaTeX. These can be processed by PdfLaTeX, XeLaTeX or
4141
LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are
42-
found in :doc:`/tutorials/text/pgf`.
42+
found in :ref:`pgf`.
4343

4444
.. image:: /_static/pgf_preamble.*
4545

‎doc/users/prev_whats_new/whats_new_1.4.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -406,7 +406,7 @@ instead of ``:context:`` any time you want to reset the context.
406406

407407
Legend and PathEffects documentation
408408
------------------------------------
409-
The :doc:`/tutorials/intermediate/legend_guide` and :doc:`/tutorials/advanced/patheffects_guide` have both been
409+
The :ref:`legend_guide` and :ref:`patheffects_guide` have both been
410410
updated to better reflect the full potential of each of these powerful
411411
features.
412412

‎doc/users/prev_whats_new/whats_new_1.5.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,8 +104,8 @@ defining property cycles. Adding cyclers together will be like you are
104104
You can even multiply cyclers, which is like using `itertools.product`
105105
on two or more property cycles.
106106

107-
.. figure:: ../../tutorials/intermediate/images/sphx_glr_color_cycle_001.png
108-
:target: ../../tutorials/intermediate/color_cycle.html
107+
.. figure:: /users/explain/artists/images/sphx_glr_color_cycle_001.png
108+
:target: /users/explain/artists/color_cycle.html
109109
:align: center
110110
:scale: 50
111111

‎doc/users/prev_whats_new/whats_new_2.2.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Features include:
3232
- Nested `~.GridSpec` layouts using `~.GridSpecFromSubplotSpec`.
3333

3434
For more details and capabilities please see the new tutorial:
35-
:doc:`/tutorials/intermediate/constrainedlayout_guide`
35+
:ref:`constrainedlayout_guide`
3636

3737
Note the new API to access this:
3838

‎doc/users/prev_whats_new/whats_new_3.3.0.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ or as a string (with single-character Axes labels):
5050
ha='center', va='center', fontsize=36,
5151
color='darkgrey')
5252

53-
See :doc:`/gallery/subplots_axes_and_figures/mosaic` for more details and examples.
53+
See :ref:`mosaic` for more details and examples.
5454

5555
``GridSpec.subplots()``
5656
-----------------------

0 commit comments

Comments
 (0)