diff --git a/.circleci/config.yml b/.circleci/config.yml index d4fecc8a5394..440c3f0e637b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -97,9 +97,12 @@ commands: - run: name: Install Python dependencies command: | + # remove when sphinx-gallery releases #1071: python -m pip install --user \ numpy<< parameters.numpy_version >> codecov coverage \ -r requirements/doc/doc-requirements.txt + python -m pip install --no-deps --user \ + git+https://github.com/sphinx-gallery/sphinx-gallery.git python -m pip install --no-deps --user \ git+https://github.com/matplotlib/mpl-sphinx-theme.git diff --git a/.flake8 b/.flake8 index 450b743e87b1..ee739cdf4231 100644 --- a/.flake8 +++ b/.flake8 @@ -55,22 +55,22 @@ per-file-ignores = lib/pylab.py: F401, F403 doc/conf.py: E402 - galleries/tutorials/advanced/path_tutorial.py: E402 - galleries/tutorials/advanced/patheffects_guide.py: E402 - galleries/tutorials/advanced/transforms_tutorial.py: E402, E501 - galleries/tutorials/colors/colormaps.py: E501 - galleries/tutorials/colors/colors.py: E402 - galleries/tutorials/intermediate/artists.py: E402 - galleries/tutorials/intermediate/constrainedlayout_guide.py: E402 - galleries/tutorials/intermediate/legend_guide.py: E402 - galleries/tutorials/intermediate/tight_layout_guide.py: E402 - galleries/tutorials/introductory/animation_tutorial.py: E501 - galleries/tutorials/introductory/images.py: E501 - galleries/tutorials/introductory/pyplot.py: E402, E501 - galleries/tutorials/text/annotations.py: E402, E501 - galleries/tutorials/text/mathtext.py: E501 - galleries/tutorials/text/text_intro.py: E402 - galleries/tutorials/text/text_props.py: E501 + galleries/users_explain/artists/paths.py: E402 + galleries/users_explain/artists/patheffects_guide.py: E402 + galleries/users_explain/artists/transforms_tutorial.py: E402, E501 + galleries/users_explain/colors/colormaps.py: E501 + galleries/users_explain/colors/colors.py: E402 + galleries/tutorials/artists.py: E402 + galleries/users_explain/axes/constrainedlayout_guide.py: E402 + galleries/users_explain/axes/legend_guide.py: E402 + galleries/users_explain/axes/tight_layout_guide.py: E402 + galleries/users_explain/animations/animations.py: E501 + galleries/tutorials/images.py: E501 + galleries/tutorials/pyplot.py: E402, E501 + galleries/users_explain/text/annotations.py: E402, E501 + galleries/users_explain/text/mathtext.py: E501 + galleries/users_explain/text/text_intro.py: E402 + galleries/users_explain/text/text_props.py: E501 galleries/examples/animation/frame_grabbing_sgskip.py: E402 galleries/examples/images_contours_and_fields/tricontour_demo.py: E201 diff --git a/doc/Makefile b/doc/Makefile index c2534ed043e8..53b7c02b68fa 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -22,6 +22,7 @@ clean: rm -rf "$(SOURCEDIR)/gallery" rm -rf "$(SOURCEDIR)/plot_types" rm -rf "$(SOURCEDIR)/tutorials" + rm -rf "$(SOURCEDIR)/users/explain" rm -rf "$(SOURCEDIR)/savefig" rm -rf "$(SOURCEDIR)/sphinxext/__pycache__" rm -f $(SOURCEDIR)/_static/constrained_layout*.png diff --git a/doc/api/index.rst b/doc/api/index.rst index 2e8c33fa05e5..c699e7520c92 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -75,7 +75,7 @@ programmatic plot generation. Further reading: - The `matplotlib.pyplot` function reference -- :doc:`/tutorials/introductory/pyplot` +- :ref:`pyplot_tutorial` - :ref:`Pyplot examples ` .. _api-index: diff --git a/doc/api/prev_api_changes/api_changes_1.4.x.rst b/doc/api/prev_api_changes/api_changes_1.4.x.rst index c12d40a67991..9f2436a81df7 100644 --- a/doc/api/prev_api_changes/api_changes_1.4.x.rst +++ b/doc/api/prev_api_changes/api_changes_1.4.x.rst @@ -88,7 +88,7 @@ original location: * The legend handler interface has changed from a callable, to any object which implements the ``legend_artists`` method (a deprecation phase will see this interface be maintained for v1.4). See - :doc:`/tutorials/intermediate/legend_guide` for further details. Further legend changes + :ref:`legend_guide` for further details. Further legend changes include: * ``matplotlib.axes.Axes._get_legend_handles`` now returns a generator of diff --git a/doc/api/prev_api_changes/api_changes_2.2.0.rst b/doc/api/prev_api_changes/api_changes_2.2.0.rst index f13fe2a246f0..83369b66f8ab 100644 --- a/doc/api/prev_api_changes/api_changes_2.2.0.rst +++ b/doc/api/prev_api_changes/api_changes_2.2.0.rst @@ -9,7 +9,7 @@ New dependency `kiwisolver `__ is now a required dependency to support the new constrained_layout, see -:doc:`/tutorials/intermediate/constrainedlayout_guide` for +:ref:`constrainedlayout_guide` for more details. diff --git a/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst index f6d6459be8f1..df08097dba03 100644 --- a/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst +++ b/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst @@ -24,7 +24,7 @@ library, so using it should be safe, but layouts may not be exactly the same as more development takes place. Details of using ``constrained_layout``, and its algorithm are available at -:doc:`/tutorials/intermediate/constrainedlayout_guide` +:ref:`constrainedlayout_guide` ``plt.subplot`` re-selection without keyword arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/api/style_api.rst b/doc/api/style_api.rst index 84bbe8b25c84..1f124965da61 100644 --- a/doc/api/style_api.rst +++ b/doc/api/style_api.rst @@ -5,7 +5,7 @@ Styles are predefined sets of `.rcParams` that define the visual appearance of a plot. -:doc:`/tutorials/introductory/customizing` describes the mechanism and usage +:ref:`customizing` describes the mechanism and usage of styles. The :doc:`/gallery/style_sheets/style_sheets_reference` gives an overview of diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst index fc6c4cbad6d1..f14918314b97 100644 --- a/doc/api/toolkits/mplot3d.rst +++ b/doc/api/toolkits/mplot3d.rst @@ -12,7 +12,7 @@ and feel as regular 2D plots. Not the fastest or most feature complete 3D library out there, but it ships with Matplotlib and thus may be a lighter weight solution for some use cases. -See the :doc:`mplot3d tutorial ` for +See the :ref:`mplot3d tutorial ` for more information. .. image:: /_static/demo_mplot3d.png diff --git a/doc/conf.py b/doc/conf.py index dfb6b6395089..b550dc9c89ef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -213,11 +213,14 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, gallery_conf['image_srcset'] = [] return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs) -gallery_dirs = [f'{ed}' for ed in ['gallery', 'tutorials', 'plot_types'] +gallery_dirs = [f'{ed}' for ed in + ['gallery', 'tutorials', 'plot_types', 'users/explain'] if f'{ed}/*' not in skip_subdirs] -example_dirs = [f'../galleries/{gd}'.replace('gallery', 'examples') - for gd in gallery_dirs] +example_dirs = [] +for gd in gallery_dirs: + gd = gd.replace('gallery', 'examples').replace('users/explain', 'users_explain') + example_dirs += [f'../galleries/{gd}'] sphinx_gallery_conf = { 'backreferences_dir': Path('api') / Path('_as_gen'), @@ -244,6 +247,7 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, 'thumbnail_size': (320, 224), 'within_subsection_order': gallery_order.subsectionorder, 'capture_repr': (), + 'copyfile_regex': r'.*\.rst', } if 'plot_gallery=0' in sys.argv: diff --git a/doc/devel/MEP/MEP29.rst b/doc/devel/MEP/MEP29.rst index d937889d55de..fce4e3c5072c 100644 --- a/doc/devel/MEP/MEP29.rst +++ b/doc/devel/MEP/MEP29.rst @@ -54,7 +54,7 @@ Improvements to use the html.parser from the standard library. * Computation of text fragment positions could benefit from the OffsetFrom - class. See for example item 5 in `Using Complex Coordinates with Annotations `_ + class. See for example item 5 in `Using Complex Coordinates with Annotations `_ Problems -------- diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 51c5f7e19eb0..37a7bb4ba9f7 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -202,7 +202,7 @@ Documents can be linked with the ``:doc:`` directive: See the :doc:`/users/installing/index` - See the tutorial :doc:`/tutorials/introductory/quick_start` + See the tutorial :ref:`quick_start` See the example :doc:`/gallery/lines_bars_and_markers/simple_plot` @@ -210,7 +210,7 @@ will render as: See the :doc:`/users/installing/index` - See the tutorial :doc:`/tutorials/introductory/quick_start` + See the tutorial :ref:`quick_start` See the example :doc:`/gallery/lines_bars_and_markers/simple_plot` @@ -858,10 +858,9 @@ The first comment block is treated as ReST_ text. The other comment blocks render as comments in :doc:`/gallery/lines_bars_and_markers/simple_plot`. Tutorials are made with the exact same mechanism, except they are longer, and -typically have more than one comment block (i.e. -:doc:`/tutorials/introductory/quick_start`). The first comment block -can be the same as the example above. Subsequent blocks of ReST text are -delimited by the line ``# %%`` : +typically have more than one comment block (i.e. :ref:`quick_start`). The +first comment block can be the same as the example above. Subsequent blocks of +ReST text are delimited by the line ``# %%`` : .. code-block:: python diff --git a/doc/index.rst b/doc/index.rst index 1c608c0d62cb..4e593f0688dc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -49,9 +49,9 @@ Learning resources Tutorials ^^^ - - :doc:`Quick-start guide ` + - :ref:`Quick-start guide ` - :doc:`Plot types ` - - :ref:`Introductory tutorials ` + - :ref:`users-guide-using` - :doc:`External learning resources ` .. grid-item-card:: @@ -69,11 +69,8 @@ Learning resources Understand how Matplotlib works ^^^ - - The :ref:`users-guide-explain` in the :doc:`Users guide - ` - - Many of the :ref:`Intermediate ` and - :ref:`Advanced ` tutorials have explanatory - material + - :ref:`users-guide-explain` in the :doc:`Users guide + ` has a number of advanced topics. .. grid-item-card:: :padding: 2 diff --git a/doc/users/explain/index.rst b/doc/users/explain/index.rst deleted file mode 100644 index d70886dc6878..000000000000 --- a/doc/users/explain/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _users-guide-explain: - -.. redirect-from:: /users/explain - -Explanations ------------- - -.. toctree:: - :maxdepth: 2 - - api_interfaces.rst - figures.rst - backends.rst - writing_a_backend_pyplot_interface.rst - interactive.rst - fonts.rst - event_handling.rst - performance.rst - interactive_guide.rst diff --git a/doc/users/faq/howto_faq.rst b/doc/users/faq/howto_faq.rst index a7cd0ab0e643..f43494ff4f12 100644 --- a/doc/users/faq/howto_faq.rst +++ b/doc/users/faq/howto_faq.rst @@ -97,7 +97,7 @@ actually perform such a rendering and inspect the result. Find all objects in a figure of a certain type ---------------------------------------------- -Every Matplotlib artist (see :doc:`/tutorials/intermediate/artists`) has a method +Every Matplotlib artist (see :ref:`artists_tutorial`) has a method called :meth:`~matplotlib.artist.Artist.findobj` that can be used to recursively search the artist for any artists it may contain that meet some criteria (e.g., match all :class:`~matplotlib.lines.Line2D` @@ -183,8 +183,8 @@ multiple ways to fix this: `.pyplot.subplots_adjust`. - Use one of the automatic layout mechanisms: - - constrained layout (:doc:`/tutorials/intermediate/constrainedlayout_guide`) - - tight layout (:doc:`/tutorials/intermediate/tight_layout_guide`) + - constrained layout (:ref:`constrainedlayout_guide`) + - tight layout (:ref:`tight_layout_guide`) - Calculate good values from the size of the plot elements yourself (:doc:`/gallery/subplots_axes_and_figures/auto_subplots_adjust`) diff --git a/doc/users/faq/troubleshooting_faq.rst b/doc/users/faq/troubleshooting_faq.rst index f88cb19d1395..8deb7f02ae32 100644 --- a/doc/users/faq/troubleshooting_faq.rst +++ b/doc/users/faq/troubleshooting_faq.rst @@ -106,7 +106,7 @@ provide the following information in your e-mail to the `mailing list GitHub, PyPI, or `Anaconda `_). * Any customizations to your ``matplotlibrc`` file (see - :doc:`/tutorials/introductory/customizing`). + :ref:`customizing`). * If the problem is reproducible, please try to provide a *minimal*, standalone Python script that demonstrates the problem. This is *the* critical step. diff --git a/doc/users/getting_started/index.rst b/doc/users/getting_started/index.rst index ec1f769e5e78..68d62232ddc9 100644 --- a/doc/users/getting_started/index.rst +++ b/doc/users/getting_started/index.rst @@ -51,5 +51,5 @@ Where to go next - Check out :doc:`Plot types ` to get an overview of the types of plots you can create with Matplotlib. -- Learn Matplotlib from the ground up in the - :doc:`Quick-start guide `. +- Learn Matplotlib from the ground up in the :ref:`Quick-start guide + `. diff --git a/doc/users/installing/index.rst b/doc/users/installing/index.rst index 1b6fdf65055f..f91ee8f94e96 100644 --- a/doc/users/installing/index.rst +++ b/doc/users/installing/index.rst @@ -219,7 +219,7 @@ example:: This will give you additional information about which backends Matplotlib is loading, version information, and more. At this point you might want to make -sure you understand Matplotlib's :doc:`configuration ` +sure you understand Matplotlib's :ref:`configuration ` process, governed by the :file:`matplotlibrc` configuration file which contains instructions within and the concept of the Matplotlib backend. diff --git a/doc/users/prev_whats_new/dflt_style_changes.rst b/doc/users/prev_whats_new/dflt_style_changes.rst index 48ff86f56a73..9be573c050e3 100644 --- a/doc/users/prev_whats_new/dflt_style_changes.rst +++ b/doc/users/prev_whats_new/dflt_style_changes.rst @@ -98,7 +98,7 @@ are only specified via hex values. To access these colors outside of the property cycling the notation for colors ``'CN'``, where ``N`` takes values 0-9, was added to denote the first 10 colors in :rc:`axes.prop_cycle`. See -:doc:`/tutorials/colors/colors` for more details. +:ref:`colors_def` for more details. To restore the old color cycle use @@ -147,7 +147,7 @@ watch Nathaniel Smith and Stéfan van der Walt's talk from SciPy2015. See `here for many more details `__ about the other alternatives and the tools used to create the color map. For details on all of the colormaps available in matplotlib see -:doc:`/tutorials/colors/colormaps`. +:ref:`colormaps`. .. raw:: html diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst index c2d761a25031..523e68ef1a8a 100644 --- a/doc/users/prev_whats_new/whats_new_0.99.rst +++ b/doc/users/prev_whats_new/whats_new_0.99.rst @@ -11,11 +11,11 @@ What's new in Matplotlib 0.99 (Aug 29, 2009) New documentation ----------------- -Jae-Joon Lee has written two new guides :doc:`/tutorials/intermediate/legend_guide` +Jae-Joon Lee has written two new guides :ref:`legend_guide` and :ref:`plotting-guide-annotation`. Michael Sarahan has written -:doc:`/tutorials/introductory/images`. John Hunter has written two new tutorials on -working with paths and transformations: :doc:`/tutorials/advanced/path_tutorial` and -:doc:`/tutorials/advanced/transforms_tutorial`. +:ref:`image_tutorial`. John Hunter has written two new tutorials on +working with paths and transformations: :ref:`paths` and +:ref:`transforms_tutorial`. .. _whats-new-mplot3d: @@ -26,7 +26,7 @@ Reinier Heeres has ported John Porter's mplot3d over to the new matplotlib transformations framework, and it is now available as a toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl installs). See :ref:`mplot3d-examples-index` and -:doc:`/tutorials/toolkits/mplot3d`. +:ref:`mplot3d`. .. plot:: diff --git a/doc/users/prev_whats_new/whats_new_1.0.rst b/doc/users/prev_whats_new/whats_new_1.0.rst index ab902977cb1e..c8da886c9097 100644 --- a/doc/users/prev_whats_new/whats_new_1.0.rst +++ b/doc/users/prev_whats_new/whats_new_1.0.rst @@ -23,7 +23,7 @@ Sophisticated subplot grid layout Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for doing complex subplot layouts, featuring row and column spans and -more. See :doc:`/tutorials/intermediate/arranging_axes` for a tutorial +more. See :ref:`arranging_axes` for a tutorial overview. .. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_001.png diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst index 901351466fac..cad5cc33c773 100644 --- a/doc/users/prev_whats_new/whats_new_1.1.rst +++ b/doc/users/prev_whats_new/whats_new_1.1.rst @@ -85,7 +85,7 @@ The usage of this functionality can be as simple as :: and it will adjust the spacing between subplots so that the axis labels do not overlap with neighboring subplots. A -:doc:`/tutorials/intermediate/tight_layout_guide` has been created to show how to use +:ref:`tight_layout_guide` has been created to show how to use this new tool. PyQT4, PySide, and IPython @@ -114,7 +114,7 @@ legends for complex plots such as :meth:`~matplotlib.pyplot.stem` plots will now display correctly. Second, the 'best' placement of a legend has been improved in the presence of NANs. -See the :doc:`/tutorials/intermediate/legend_guide` for more detailed explanation and +See the :ref:`legend_guide` for more detailed explanation and examples. .. 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 improved to bring the class towards feature-parity with regular Axes objects -* Documentation for :doc:`/tutorials/toolkits/mplot3d` was significantly expanded +* Documentation for :ref:`mplot3d` was significantly expanded * Axis labels and orientation improved diff --git a/doc/users/prev_whats_new/whats_new_1.2.rst b/doc/users/prev_whats_new/whats_new_1.2.rst index 3bfa20e671be..46856ab4fcf5 100644 --- a/doc/users/prev_whats_new/whats_new_1.2.rst +++ b/doc/users/prev_whats_new/whats_new_1.2.rst @@ -39,7 +39,7 @@ PGF/TikZ backend Peter Würtz wrote a backend that allows matplotlib to export figures as drawing commands for LaTeX. These can be processed by PdfLaTeX, XeLaTeX or LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are -found in :doc:`/tutorials/text/pgf`. +found in :ref:`pgf`. .. image:: /_static/pgf_preamble.* diff --git a/doc/users/prev_whats_new/whats_new_1.4.rst b/doc/users/prev_whats_new/whats_new_1.4.rst index 057f547c9f4c..b8a85638646b 100644 --- a/doc/users/prev_whats_new/whats_new_1.4.rst +++ b/doc/users/prev_whats_new/whats_new_1.4.rst @@ -406,7 +406,7 @@ instead of ``:context:`` any time you want to reset the context. Legend and PathEffects documentation ------------------------------------ -The :doc:`/tutorials/intermediate/legend_guide` and :doc:`/tutorials/advanced/patheffects_guide` have both been +The :ref:`legend_guide` and :ref:`patheffects_guide` have both been updated to better reflect the full potential of each of these powerful features. diff --git a/doc/users/prev_whats_new/whats_new_1.5.rst b/doc/users/prev_whats_new/whats_new_1.5.rst index b94355b97b93..0dd142d989f0 100644 --- a/doc/users/prev_whats_new/whats_new_1.5.rst +++ b/doc/users/prev_whats_new/whats_new_1.5.rst @@ -104,8 +104,8 @@ defining property cycles. Adding cyclers together will be like you are You can even multiply cyclers, which is like using `itertools.product` on two or more property cycles. -.. figure:: ../../tutorials/intermediate/images/sphx_glr_color_cycle_001.png - :target: ../../tutorials/intermediate/color_cycle.html +.. figure:: /users/explain/artists/images/sphx_glr_color_cycle_001.png + :target: /users/explain/artists/color_cycle.html :align: center :scale: 50 diff --git a/doc/users/prev_whats_new/whats_new_2.2.rst b/doc/users/prev_whats_new/whats_new_2.2.rst index 77b9056048f4..2071c131a5b2 100644 --- a/doc/users/prev_whats_new/whats_new_2.2.rst +++ b/doc/users/prev_whats_new/whats_new_2.2.rst @@ -32,7 +32,7 @@ Features include: - Nested `~.GridSpec` layouts using `~.GridSpecFromSubplotSpec`. For more details and capabilities please see the new tutorial: - :doc:`/tutorials/intermediate/constrainedlayout_guide` + :ref:`constrainedlayout_guide` Note the new API to access this: diff --git a/doc/users/prev_whats_new/whats_new_3.3.0.rst b/doc/users/prev_whats_new/whats_new_3.3.0.rst index 58959627246a..45507b4c1dcf 100644 --- a/doc/users/prev_whats_new/whats_new_3.3.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.3.0.rst @@ -50,7 +50,7 @@ or as a string (with single-character Axes labels): ha='center', va='center', fontsize=36, color='darkgrey') -See :doc:`/gallery/subplots_axes_and_figures/mosaic` for more details and examples. +See :ref:`mosaic` for more details and examples. ``GridSpec.subplots()`` ----------------------- diff --git a/doc/users/prev_whats_new/whats_new_3.4.0.rst b/doc/users/prev_whats_new/whats_new_3.4.0.rst index 85a2f8a80975..f90a95c7f126 100644 --- a/doc/users/prev_whats_new/whats_new_3.4.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.4.0.rst @@ -582,7 +582,7 @@ If the center of symmetry is different from 0, it can be set with the *vcenter* argument. To manually set the range of `~.matplotlib.colors.CenteredNorm`, use the *halfrange* argument. -See :doc:`/tutorials/colors/colormapnorms` for an example and more details +See :ref:`colormapnorms` for an example and more details about data normalization. New ``FuncNorm`` for arbitrary normalizations @@ -617,8 +617,8 @@ forward and inverse. size=16, va='center', ha='center') plt.show() -See :doc:`/tutorials/colors/colormapnorms` for an example and more details -about data normalization. +See :ref:`colormapnorms` for an example and more details about data +normalization. GridSpec-based colorbars can now be positioned above or to the left of the main axes ------------------------------------------------------------------------------------ diff --git a/doc/users/prev_whats_new/whats_new_3.7.0.rst b/doc/users/prev_whats_new/whats_new_3.7.0.rst index 96ac42be38f2..1834cbf3726f 100644 --- a/doc/users/prev_whats_new/whats_new_3.7.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.7.0.rst @@ -336,7 +336,7 @@ by a *loc* keyword argument that starts with the string "outside". The codes are unique from axes codes, in that "outside upper right" will make room at the top of the figure for the legend, whereas "outside right upper" will make room on the right-hand side of the figure. -See :doc:`/tutorials/intermediate/legend_guide` for details. +See :ref:`legend_guide` for details. Per-subplot keyword arguments in ``subplot_mosaic`` @@ -445,7 +445,7 @@ functions can e.g. attach callbacks or modify the toolbar. See New & Improved Narrative Documentation ====================================== -* Brand new :doc:`Animations ` tutorial. +* Brand new :ref:`Animations ` tutorial. * New grouped and stacked `bar chart <../../gallery/index.html#lines_bars_and_markers>`_ examples. * New section for new contributors and reorganized git instructions in the :ref:`contributing guide`. -* Restructured :doc:`/tutorials/text/annotations` tutorial. +* Restructured :ref:`annotations` tutorial. diff --git a/doc/users/project/history.rst b/doc/users/project/history.rst index 3291d7e43f8b..18a94793736f 100644 --- a/doc/users/project/history.rst +++ b/doc/users/project/history.rst @@ -68,10 +68,10 @@ The Matplotlib code is conceptually divided into three parts: the *pylab interface* is the set of functions provided by :mod:`pylab` which allow the user to create plots with code quite similar to MATLAB figure generating code -(:doc:`/tutorials/introductory/pyplot`). The *Matplotlib frontend* or *Matplotlib +(:ref:`pyplot_tutorial`). The *Matplotlib frontend* or *Matplotlib API* is the set of classes that do the heavy lifting, creating and managing figures, text, lines, plots and so on -(:doc:`/tutorials/intermediate/artists`). This is an abstract interface that knows +(:ref:`artists_tutorial`). This is an abstract interface that knows nothing about output. The *backends* are device-dependent drawing devices, aka renderers, that transform the frontend representation to hardcopy or a display device (:ref:`what-is-a-backend`). Example diff --git a/galleries/examples/axes_grid1/simple_axes_divider1.py b/galleries/examples/axes_grid1/simple_axes_divider1.py index 0a35ebc92e6e..4b7edc27ae9b 100644 --- a/galleries/examples/axes_grid1/simple_axes_divider1.py +++ b/galleries/examples/axes_grid1/simple_axes_divider1.py @@ -3,7 +3,7 @@ Simple Axes Divider 1 ===================== -See also :doc:`/tutorials/toolkits/axes_grid`. +See also :ref:`axes_grid`. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/axes_grid1/simple_axes_divider3.py b/galleries/examples/axes_grid1/simple_axes_divider3.py index e9573f3c5c2a..54050633d4ea 100644 --- a/galleries/examples/axes_grid1/simple_axes_divider3.py +++ b/galleries/examples/axes_grid1/simple_axes_divider3.py @@ -3,7 +3,7 @@ Simple axes divider 3 ===================== -See also :doc:`/tutorials/toolkits/axes_grid`. +See also :ref:`axes_grid`. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/color/color_cycle_default.py b/galleries/examples/color/color_cycle_default.py index ea81aa4fb1e6..a41ff5f63ff8 100644 --- a/galleries/examples/color/color_cycle_default.py +++ b/galleries/examples/color/color_cycle_default.py @@ -4,7 +4,7 @@ ==================================== Display the colors from the default prop_cycle, which is obtained from the -:doc:`rc parameters`. +:ref:`rc parameters`. """ import matplotlib.pyplot as plt import numpy as np diff --git a/galleries/examples/color/color_demo.py b/galleries/examples/color/color_demo.py index b36585b2e188..8c4b7756cc3e 100644 --- a/galleries/examples/color/color_demo.py +++ b/galleries/examples/color/color_demo.py @@ -30,7 +30,7 @@ For more information on colors in matplotlib see -* the :doc:`/tutorials/colors/colors` tutorial; +* the :ref:`colors_def` tutorial; * the `matplotlib.colors` API; * the :doc:`/gallery/color/named_colors` example. """ diff --git a/galleries/examples/color/colormap_reference.py b/galleries/examples/color/colormap_reference.py index 09d4a1885116..ee01d7432b37 100644 --- a/galleries/examples/color/colormap_reference.py +++ b/galleries/examples/color/colormap_reference.py @@ -8,9 +8,9 @@ A reversed version of each of these colormaps is available by appending ``_r`` to the name, as shown in :ref:`reverse-cmap`. -See :doc:`/tutorials/colors/colormaps` for an in-depth discussion about +See :ref:`colormaps` for an in-depth discussion about colormaps, including colorblind-friendliness, and -:doc:`/tutorials/colors/colormap-manipulation` for a guide to creating +:ref:`colormap-manipulation` for a guide to creating colormaps. """ diff --git a/galleries/examples/color/custom_cmap.py b/galleries/examples/color/custom_cmap.py index da064401486e..ea3c06e13cac 100644 --- a/galleries/examples/color/custom_cmap.py +++ b/galleries/examples/color/custom_cmap.py @@ -4,9 +4,9 @@ ========================================= For more detail on creating and manipulating colormaps see -:doc:`/tutorials/colors/colormap-manipulation`. +:ref:`colormap-manipulation`. -Creating a :doc:`colormap ` from a list of colors +Creating a :ref:`colormap ` from a list of colors can be done with the `.LinearSegmentedColormap.from_list` method. You must pass a list of RGB tuples that define the mixture of colors from 0 to 1. diff --git a/galleries/examples/color/named_colors.py b/galleries/examples/color/named_colors.py index 9245bbb42727..c6cba68ab434 100644 --- a/galleries/examples/color/named_colors.py +++ b/galleries/examples/color/named_colors.py @@ -6,7 +6,7 @@ This plots a list of the named colors supported in matplotlib. For more information on colors in matplotlib see -* the :doc:`/tutorials/colors/colors` tutorial; +* the :ref:`colors_def` tutorial; * the `matplotlib.colors` API; * the :doc:`/gallery/color/color_demo`. diff --git a/galleries/examples/event_handling/README.txt b/galleries/examples/event_handling/README.txt index 46aed29b56bc..44aa9cf3ac6a 100644 --- a/galleries/examples/event_handling/README.txt +++ b/galleries/examples/event_handling/README.txt @@ -3,7 +3,7 @@ Event handling ============== -Matplotlib supports :doc:`event handling` with +Matplotlib supports :ref:`event handling ` with a GUI neutral event model, so you can connect to Matplotlib events without knowledge of what user interface Matplotlib will ultimately be plugged in to. This has two advantages: the code you write will be more portable, and diff --git a/galleries/examples/images_contours_and_fields/contour_image.py b/galleries/examples/images_contours_and_fields/contour_image.py index e03ec7a0402e..250256f4771f 100644 --- a/galleries/examples/images_contours_and_fields/contour_image.py +++ b/galleries/examples/images_contours_and_fields/contour_image.py @@ -9,8 +9,8 @@ The emphasis in this demo is on showing how to make contours register correctly on images, and on how to get both of them oriented as desired. -In particular, note the usage of the :doc:`"origin" and "extent" -` keyword arguments to imshow and +In particular, note the usage of the :ref:`"origin" and "extent" +` keyword arguments to imshow and contour. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/images_contours_and_fields/image_demo.py b/galleries/examples/images_contours_and_fields/image_demo.py index 295c48cf3bcd..884e68172698 100644 --- a/galleries/examples/images_contours_and_fields/image_demo.py +++ b/galleries/examples/images_contours_and_fields/image_demo.py @@ -134,8 +134,8 @@ # x[0, 0] in the upper left or lower right by using the origin parameter. # You can also control the default setting image.origin in your # :ref:`matplotlibrc file `. For more on -# this topic see the :doc:`complete guide on origin and extent -# `. +# this topic see the :ref:`complete guide on origin and extent +# `. x = np.arange(120).reshape((10, 12)) diff --git a/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py b/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py index abd8d6750e70..c695bc51c176 100644 --- a/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py +++ b/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py @@ -14,7 +14,7 @@ line. *Note*: The dash style can also be configured via a -:doc:`property_cycle ` +:ref:`property_cycle ` by passing a list of dash sequences using the keyword *dashes* to the cycler. This is not shown within this example. diff --git a/galleries/examples/lines_bars_and_markers/linestyles.py b/galleries/examples/lines_bars_and_markers/linestyles.py index cf4bfa0eb3a6..f3ce3aa6e7ec 100644 --- a/galleries/examples/lines_bars_and_markers/linestyles.py +++ b/galleries/examples/lines_bars_and_markers/linestyles.py @@ -13,7 +13,7 @@ *Note*: The dash style can also be configured via `.Line2D.set_dashes` as shown in :doc:`/gallery/lines_bars_and_markers/line_demo_dash_control` and passing a list of dash sequences using the keyword *dashes* to the -cycler in :doc:`property_cycle `. +cycler in :ref:`property_cycle `. """ import matplotlib.pyplot as plt import numpy as np diff --git a/galleries/examples/lines_bars_and_markers/marker_reference.py b/galleries/examples/lines_bars_and_markers/marker_reference.py index 557f988b7c0c..f99afb08e143 100644 --- a/galleries/examples/lines_bars_and_markers/marker_reference.py +++ b/galleries/examples/lines_bars_and_markers/marker_reference.py @@ -101,7 +101,7 @@ def split_list(a_list): # Markers created from TeX symbols # ================================ # -# Use :doc:`MathText `, to use custom marker symbols, +# Use :ref:`MathText `, to use custom marker symbols, # like e.g. ``"$\u266B$"``. For an overview over the STIX font symbols refer # to the `STIX font table `_. # Also see the :doc:`/gallery/text_labels_and_annotations/stix_fonts_demo`. diff --git a/galleries/examples/lines_bars_and_markers/scatter_hist.py b/galleries/examples/lines_bars_and_markers/scatter_hist.py index 1ee745963a80..9e4598a15957 100644 --- a/galleries/examples/lines_bars_and_markers/scatter_hist.py +++ b/galleries/examples/lines_bars_and_markers/scatter_hist.py @@ -60,7 +60,7 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy): # -------------------------------------------- # # We define a gridspec with unequal width- and height-ratios to achieve desired -# layout. Also see the :doc:`/tutorials/intermediate/arranging_axes` tutorial. +# layout. Also see the :ref:`arranging_axes` tutorial. # Start with a square Figure. fig = plt.figure(figsize=(6, 6)) diff --git a/galleries/examples/misc/tickedstroke_demo.py b/galleries/examples/misc/tickedstroke_demo.py index 9dbe77025d92..451d7fa6fe1a 100644 --- a/galleries/examples/misc/tickedstroke_demo.py +++ b/galleries/examples/misc/tickedstroke_demo.py @@ -6,7 +6,7 @@ Matplotlib's :mod:`.patheffects` can be used to alter the way paths are drawn at a low enough level that they can affect almost anything. -The :doc:`patheffects guide` +The :ref:`patheffects guide` details the use of patheffects. The `~matplotlib.patheffects.TickedStroke` patheffect illustrated here diff --git a/galleries/examples/pyplots/pyplot_text.py b/galleries/examples/pyplots/pyplot_text.py index f327e6014807..9fb9f4f1608c 100644 --- a/galleries/examples/pyplots/pyplot_text.py +++ b/galleries/examples/pyplots/pyplot_text.py @@ -8,7 +8,7 @@ objects can be placed in the axes using `~.pyplot.text`. You can use TeX-like mathematical typesetting in all texts; see also -:doc:`/tutorials/text/mathtext`. +:ref:`mathtext`. .. redirect-from:: /gallery/pyplots/pyplot_mathtext """ diff --git a/galleries/examples/shapes_and_collections/artist_reference.py b/galleries/examples/shapes_and_collections/artist_reference.py index 853cc21d10f1..048018a9898e 100644 --- a/galleries/examples/shapes_and_collections/artist_reference.py +++ b/galleries/examples/shapes_and_collections/artist_reference.py @@ -1,4 +1,6 @@ """ +.. _artist_reference: + ================================ Reference for Matplotlib artists ================================ diff --git a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py index bf809061d59a..3bd0d3f2bec1 100644 --- a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py +++ b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py @@ -12,14 +12,14 @@ almost always simpler and good enough to either set the subplot parameters manually using `.Figure.subplots_adjust`, or use one of the automatic layout mechanisms - (:doc:`/tutorials/intermediate/constrainedlayout_guide` or - :doc:`/tutorials/intermediate/tight_layout_guide`). + (:ref:`constrainedlayout_guide` or + :ref:`tight_layout_guide`). This example describes a user-defined way to read out Artist sizes and set the subplot parameters accordingly. Its main purpose is to illustrate some advanced concepts like reading out text positions, working with bounding boxes and transforms and using -:ref:`events `. But it can also serve as a starting +:ref:`events `. But it can also serve as a starting point if you want to automate the layouting and need more flexibility than tight layout and constrained layout. diff --git a/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py b/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py index 2a375659dfc5..f16f419ece7a 100644 --- a/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py +++ b/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py @@ -7,8 +7,8 @@ a figure so that there are no overlaps between axes objects and labels on the axes. -See :doc:`/tutorials/intermediate/constrainedlayout_guide` for more details and -:doc:`/tutorials/intermediate/tight_layout_guide` for an alternative. +See :ref:`constrainedlayout_guide` for more details and +:ref:`tight_layout_guide` for an alternative. """ diff --git a/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py b/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py index 55b54c327a7b..0cc5f5301db4 100644 --- a/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py +++ b/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py @@ -6,8 +6,8 @@ `~.Figure.tight_layout` attempts to resize subplots in a figure so that there are no overlaps between axes objects and labels on the axes. -See :doc:`/tutorials/intermediate/tight_layout_guide` for more details and -:doc:`/tutorials/intermediate/constrainedlayout_guide` for an alternative. +See :ref:`tight_layout_guide` for more details and +:ref:`constrainedlayout_guide` for an alternative. """ diff --git a/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py b/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py index 133fd37b5d71..bff3ea579e9e 100644 --- a/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py +++ b/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py @@ -11,7 +11,7 @@ To start with this layout (rather than removing the overlapping axes) use `~.pyplot.subplot_mosaic`. -See also :doc:`/tutorials/intermediate/arranging_axes`. +See also :ref:`arranging_axes`. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/text_labels_and_annotations/angle_annotation.py b/galleries/examples/text_labels_and_annotations/angle_annotation.py index 97561c6c2f36..419d094bb6a9 100644 --- a/galleries/examples/text_labels_and_annotations/angle_annotation.py +++ b/galleries/examples/text_labels_and_annotations/angle_annotation.py @@ -21,8 +21,8 @@ * It provides a ready-to-use solution for the problem of easily drawing angles in graphs. * It shows how to subclass a Matplotlib artist to enhance its functionality, as - well as giving a hands-on example on how to use Matplotlib's :doc:`transform - system `. + well as giving a hands-on example on how to use Matplotlib's :ref:`transform + system `. If mainly interested in the former, you may copy the below class and jump to the :ref:`angle-annotation-usage` section. diff --git a/galleries/examples/text_labels_and_annotations/annotate_transform.py b/galleries/examples/text_labels_and_annotations/annotate_transform.py index d2bfbcef4df9..b2ce1de6a0c1 100644 --- a/galleries/examples/text_labels_and_annotations/annotate_transform.py +++ b/galleries/examples/text_labels_and_annotations/annotate_transform.py @@ -5,7 +5,7 @@ This example shows how to use different coordinate systems for annotations. For a complete overview of the annotation capabilities, also see the -:doc:`annotation tutorial`. +:ref:`annotation tutorial`. .. redirect-from:: /gallery/pyplots/annotate_transform """ diff --git a/galleries/examples/text_labels_and_annotations/annotation_basic.py b/galleries/examples/text_labels_and_annotations/annotation_basic.py index 2a5b115a96b1..45211558ec44 100644 --- a/galleries/examples/text_labels_and_annotations/annotation_basic.py +++ b/galleries/examples/text_labels_and_annotations/annotation_basic.py @@ -7,7 +7,7 @@ coordinates. We modify the defaults of the arrow, to "shrink" it. For a complete overview of the annotation capabilities, also see the -:doc:`annotation tutorial`. +:ref:`annotation tutorial`. .. redirect-from:: /gallery/pyplots/annotation_basic """ diff --git a/galleries/examples/text_labels_and_annotations/annotation_demo.py b/galleries/examples/text_labels_and_annotations/annotation_demo.py index a17b60d50e0d..972a920fbd12 100644 --- a/galleries/examples/text_labels_and_annotations/annotation_demo.py +++ b/galleries/examples/text_labels_and_annotations/annotation_demo.py @@ -7,7 +7,7 @@ This includes highlighting specific points of interest and using various visual tools to call attention to this point. For a more complete and in-depth description of the annotation and text tools in Matplotlib, see the -:doc:`tutorial on annotation `. +:ref:`tutorial on annotation `. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/text_labels_and_annotations/annotation_polar.py b/galleries/examples/text_labels_and_annotations/annotation_polar.py index 910aaad6757b..bbd46478bced 100644 --- a/galleries/examples/text_labels_and_annotations/annotation_polar.py +++ b/galleries/examples/text_labels_and_annotations/annotation_polar.py @@ -6,7 +6,7 @@ This example shows how to create an annotation on a polar graph. For a complete overview of the annotation capabilities, also see the -:doc:`annotation tutorial`. +:ref:`annotations`. .. redirect-from:: /gallery/pyplots/annotation_polar """ diff --git a/galleries/examples/text_labels_and_annotations/custom_legends.py b/galleries/examples/text_labels_and_annotations/custom_legends.py index 62965a455d61..f1714a21a481 100644 --- a/galleries/examples/text_labels_and_annotations/custom_legends.py +++ b/galleries/examples/text_labels_and_annotations/custom_legends.py @@ -10,7 +10,7 @@ For more information on creating and customizing legends, see the following pages: - * :doc:`/tutorials/intermediate/legend_guide` + * :ref:`legend_guide` * :doc:`/gallery/text_labels_and_annotations/legend_demo` Sometimes you don't want a legend that is explicitly tied to data that diff --git a/galleries/examples/text_labels_and_annotations/font_family_rc.py b/galleries/examples/text_labels_and_annotations/font_family_rc.py index f7fc4376383e..e87ca7dd9b21 100644 --- a/galleries/examples/text_labels_and_annotations/font_family_rc.py +++ b/galleries/examples/text_labels_and_annotations/font_family_rc.py @@ -7,7 +7,7 @@ family names of fonts installed on user's system, or generic-families (e.g., 'serif', 'sans-serif', 'monospace', 'fantasy' or 'cursive'), or a combination of both. -(see :doc:`font tutorial `) +(see :ref:`text_props`) In the example below, we are overriding the default sans-serif generic family to include a specific (Tahoma) font. (Note that the best way to achieve this diff --git a/galleries/examples/text_labels_and_annotations/placing_text_boxes.py b/galleries/examples/text_labels_and_annotations/placing_text_boxes.py index c90921df9cba..f3b07a25e135 100644 --- a/galleries/examples/text_labels_and_annotations/placing_text_boxes.py +++ b/galleries/examples/text_labels_and_annotations/placing_text_boxes.py @@ -3,7 +3,7 @@ ================== When decorating axes with text boxes, two useful tricks are to place the text -in axes coordinates (see :doc:`/tutorials/advanced/transforms_tutorial`), +in axes coordinates (see :ref:`transforms_tutorial`), so the text doesn't move around with changes in x or y limits. You can also use the ``bbox`` property of text to surround the text with a `~matplotlib.patches.Patch` instance -- the ``bbox`` keyword argument takes a diff --git a/galleries/examples/text_labels_and_annotations/tex_demo.py b/galleries/examples/text_labels_and_annotations/tex_demo.py index 4df40191660b..5eba9a14c2b7 100644 --- a/galleries/examples/text_labels_and_annotations/tex_demo.py +++ b/galleries/examples/text_labels_and_annotations/tex_demo.py @@ -5,7 +5,7 @@ You can use TeX to render all of your Matplotlib text by setting :rc:`text.usetex` to True. This requires that you have TeX and the other -dependencies described in the :doc:`/tutorials/text/usetex` tutorial properly +dependencies described in the :ref:`usetex` tutorial properly installed on your system. Matplotlib caches processed TeX expressions, so that only the first occurrence of an expression triggers a TeX compilation. Later occurrences reuse the rendered image from the cache and are thus faster. diff --git a/galleries/examples/widgets/textbox.py b/galleries/examples/widgets/textbox.py index de94ba1d3c02..5a9dd7ff6feb 100644 --- a/galleries/examples/widgets/textbox.py +++ b/galleries/examples/widgets/textbox.py @@ -9,7 +9,7 @@ user presses enter in the textbox or leaves the textbox. Note: The `matplotlib.widgets.TextBox` widget is different from the following -static elements: :doc:`/tutorials/text/annotations` and +static elements: :ref:`annotations` and :doc:`/gallery/text_labels_and_annotations/placing_text_boxes`. """ diff --git a/galleries/tutorials/README.txt b/galleries/tutorials/README.txt deleted file mode 100644 index da744b3224c7..000000000000 --- a/galleries/tutorials/README.txt +++ /dev/null @@ -1,12 +0,0 @@ -.. _tutorials: - -Tutorials -========= - -This page contains more in-depth guides for using Matplotlib. -It is broken up into beginner, intermediate, and advanced sections, -as well as sections covering specific topics. - -For shorter examples, see our :ref:`examples page `. -You can also find :ref:`external resources ` and -a :ref:`FAQ ` in our :ref:`user guide `. diff --git a/galleries/tutorials/advanced/README.txt b/galleries/tutorials/advanced/README.txt deleted file mode 100644 index 47292163be06..000000000000 --- a/galleries/tutorials/advanced/README.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. _tutorials-advanced: - -Advanced --------- - -These tutorials cover advanced topics for experienced Matplotlib -users and developers. diff --git a/galleries/tutorials/intermediate/artists.py b/galleries/tutorials/artists.py similarity index 99% rename from galleries/tutorials/intermediate/artists.py rename to galleries/tutorials/artists.py index 9d3b5305b5d4..46303372d7ae 100644 --- a/galleries/tutorials/intermediate/artists.py +++ b/galleries/tutorials/artists.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/artists + +.. _artists_tutorial: + =============== Artist tutorial =============== @@ -716,6 +720,6 @@ class in the Matplotlib API, and the one you will be working with most # dollar signs and colors them green on the right side of the yaxis. # # -# .. include:: ../../gallery/ticks/dollar_ticks.rst +# .. include:: ../gallery/ticks/dollar_ticks.rst # :start-after: .. redirect-from:: /gallery/pyplots/dollar_ticks # :end-before: .. admonition:: References diff --git a/galleries/tutorials/introductory/images.py b/galleries/tutorials/images.py similarity index 96% rename from galleries/tutorials/introductory/images.py rename to galleries/tutorials/images.py index fc17b90f5aea..24ab2bf8f495 100644 --- a/galleries/tutorials/introductory/images.py +++ b/galleries/tutorials/images.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/introductory/images + +.. _image_tutorial: + ============== Image tutorial ============== @@ -42,8 +46,8 @@ experimenting with various plot settings. The alternative is the explicit, which is more suitable for large application development. For an explanation of the tradeoffs between the implicit and explicit interfaces see -:ref:`api_interfaces` and the :doc:`Quick start guide -` to start using the explicit interface. +:ref:`api_interfaces` and the :ref:`Quick start guide +` to start using the explicit interface. For now, let's get on with the implicit approach: """ @@ -65,7 +69,7 @@ # # Here's the image we're going to play with: # -# .. image:: ../../_static/stinkbug.png +# .. image:: ../_static/stinkbug.png # # It's a 24-bit RGB PNG image (8 bits for each of R, G, B). Depending # on where you get your data, the other kinds of image that you'll most @@ -78,7 +82,7 @@ # convert the `PIL.Image.Image` object into an 8-bit (``dtype=uint8``) numpy # array. -img = np.asarray(Image.open('../../../doc/_static/stinkbug.png')) +img = np.asarray(Image.open('../../doc/_static/stinkbug.png')) print(repr(img)) # %% @@ -227,7 +231,7 @@ # We'll use the Pillow library that we used to load the image also to resize # the image. -img = Image.open('../../../doc/_static/stinkbug.png') +img = Image.open('../../doc/_static/stinkbug.png') img.thumbnail((64, 64)) # resizes image in-place imgplot = plt.imshow(img) diff --git a/galleries/tutorials/index.rst b/galleries/tutorials/index.rst new file mode 100644 index 000000000000..899b3bbcc64e --- /dev/null +++ b/galleries/tutorials/index.rst @@ -0,0 +1,159 @@ +.. _tutorials: + +Tutorials +========= + +This page contains a few tutorials for using Matplotlib. For the old tutorials, see :ref:`below `. + +For shorter examples, see our :ref:`examples page `. +You can also find :ref:`external resources ` and +a :ref:`FAQ ` in our :ref:`user guide `. + + +.. raw:: html + +
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_pyplot_thumb.png + :alt: Pyplot tutorial + + :ref:`sphx_glr_tutorials_pyplot.py` + +.. raw:: html + +
Pyplot tutorial
+
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_images_thumb.png + :alt: Image tutorial + + :ref:`sphx_glr_tutorials_images.py` + +.. raw:: html + +
Image tutorial
+
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_lifecycle_thumb.png + :alt: The Lifecycle of a Plot + + :ref:`sphx_glr_tutorials_lifecycle.py` + +.. raw:: html + +
The Lifecycle of a Plot
+
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_artists_thumb.png + :alt: Artist tutorial + + :ref:`sphx_glr_tutorials_artists.py` + +.. raw:: html + +
Artist tutorial
+
+ + +.. raw:: html + +
+ + +.. toctree:: + :hidden: + + /tutorials/pyplot + /tutorials/images + /tutorials/lifecycle + /tutorials/artists + +.. only:: html + + .. container:: sphx-glr-footer sphx-glr-footer-gallery + + .. container:: sphx-glr-download sphx-glr-download-python + + :download:`Download all examples in Python source code: tutorials_python.zip ` + + .. container:: sphx-glr-download sphx-glr-download-jupyter + + :download:`Download all examples in Jupyter notebooks: tutorials_jupyter.zip ` + + + +.. _user_guide_tutorials: + +User guide tutorials +-------------------- + +Many of our tutorials were moved from this section to :ref:`users-guide-explain`: + +Introductory +~~~~~~~~~~~~ + +- :ref:`quick_start` +- :ref:`customizing` +- :ref:`animations` + +Intermediate +~~~~~~~~~~~~ + +- :ref:`legend_guide` +- :ref:`color_cycle` +- :ref:`constrainedlayout_guide` +- :ref:`tight_layout_guide` +- :ref:`arranging_axes` +- :ref:`autoscale` +- :ref:`imshow_extent` + +Advanced +~~~~~~~~ + +- :ref:`blitting` +- :ref:`paths` +- :ref:`patheffects_guide` +- :ref:`transforms_tutorial` + +Colors +~~~~~~ + +See :ref:`tutorials-colors`. + +Text +~~~~ + +See :ref:`tutorials-text`. + +Toolkits +~~~~~~~~ + +See :ref:`tutorials-toolkits`. diff --git a/galleries/tutorials/intermediate/README.txt b/galleries/tutorials/intermediate/README.txt deleted file mode 100644 index 5ae0dbd83c3b..000000000000 --- a/galleries/tutorials/intermediate/README.txt +++ /dev/null @@ -1,8 +0,0 @@ -.. _tutorials-intermediate: - -Intermediate ------------- - -These tutorials cover some of the more complicated classes and functions -in Matplotlib. They can be useful for particular custom and complex -visualizations. diff --git a/galleries/tutorials/introductory/README.txt b/galleries/tutorials/introductory/README.txt deleted file mode 100644 index f51300a2a840..000000000000 --- a/galleries/tutorials/introductory/README.txt +++ /dev/null @@ -1,8 +0,0 @@ -.. _tutorials-introductory: - -Introductory -------------- - -These tutorials cover the basics of creating visualizations with -Matplotlib, as well as some best-practices in using the package -effectively. diff --git a/galleries/tutorials/introductory/lifecycle.py b/galleries/tutorials/lifecycle.py similarity index 96% rename from galleries/tutorials/introductory/lifecycle.py rename to galleries/tutorials/lifecycle.py index f72197d869bd..9df59a5d229f 100644 --- a/galleries/tutorials/introductory/lifecycle.py +++ b/galleries/tutorials/lifecycle.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/introductory/lifecycle + ======================= The Lifecycle of a Plot ======================= @@ -27,8 +29,8 @@ :class:`axes.Axes` to build up the visualization in an instance of :class:`figure.Figure`. In the implicit interface, inspired by and modeled on MATLAB, we use a global state-based interface which is encapsulated in the -:mod:`.pyplot` module to plot to the "current Axes". See the :doc:`pyplot -tutorials ` for a more in-depth look at the +:mod:`.pyplot` module to plot to the "current Axes". See the :ref:`pyplot +tutorials ` for a more in-depth look at the pyplot interface. Most of the terms are straightforward but the main thing to remember @@ -85,8 +87,8 @@ # .. note:: # # Figures can have multiple axes on them. For information on how to do this, -# see the :doc:`Tight Layout tutorial -# `. +# see the :ref:`Tight Layout tutorial +# `. fig, ax = plt.subplots() @@ -149,7 +151,7 @@ # that we create. To do this we set the ``autolayout`` value of our # rcParams. For more information on controlling the style, layout, and # other features of plots with rcParams, see -# :doc:`/tutorials/introductory/customizing`. +# :ref:`customizing`. plt.rcParams.update({'figure.autolayout': True}) diff --git a/galleries/tutorials/provisional/README.txt b/galleries/tutorials/provisional/README.txt deleted file mode 100644 index cf2296f05369..000000000000 --- a/galleries/tutorials/provisional/README.txt +++ /dev/null @@ -1,14 +0,0 @@ -.. _tutorials-provisional: - -Provisional ------------ - -These tutorials cover proposed APIs of any complexity. These are here -to document features that we have released, but want to get user -feedback on before committing to them. Please have a look, try them -out and give us feedback on `gitter -`__, `discourse -`__, or the `the mailing list -`__! But, -be aware that we may change the APIs without warning in subsequent -versions. diff --git a/galleries/tutorials/introductory/pyplot.py b/galleries/tutorials/pyplot.py similarity index 97% rename from galleries/tutorials/introductory/pyplot.py rename to galleries/tutorials/pyplot.py index 8077e3255bba..b7f9245190d0 100644 --- a/galleries/tutorials/introductory/pyplot.py +++ b/galleries/tutorials/pyplot.py @@ -1,10 +1,14 @@ """ +.. redirect-from:: /tutorials/introductory/pyplot + +.. _pyplot_tutorial: + =============== Pyplot tutorial =============== An introduction to the pyplot interface. Please also see -:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib +:ref:`quick_start` for an overview of how Matplotlib works and :ref:`api_interfaces` for an explanation of the trade-offs between the supported user APIs. @@ -307,7 +311,7 @@ def f(t): # it annoying that states (specifically the current image, figure and axes) # are being maintained for you behind the scenes, don't despair: this is just a thin # stateful wrapper around an object-oriented API, which you can use -# instead (see :doc:`/tutorials/intermediate/artists`) +# instead (see :ref:`artists_tutorial`) # # If you are making lots of figures, you need to be aware of one # more thing: the memory required for a figure is not completely @@ -325,7 +329,7 @@ def f(t): # # `~.pyplot.text` can be used to add text in an arbitrary location, and # `~.pyplot.xlabel`, `~.pyplot.ylabel` and `~.pyplot.title` are used to add -# text in the indicated locations (see :doc:`/tutorials/text/text_intro` for a +# text in the indicated locations (see :ref:`text_intro` for a # more detailed example) mu, sigma = 100, 15 @@ -350,7 +354,7 @@ def f(t): # # t = plt.xlabel('my data', fontsize=14, color='red') # -# These properties are covered in more detail in :doc:`/tutorials/text/text_props`. +# These properties are covered in more detail in :ref:`text_props`. # # # Using mathematical expressions in text @@ -366,11 +370,11 @@ def f(t): # that the string is a *raw* string and not to treat backslashes as # python escapes. matplotlib has a built-in TeX expression parser and # layout engine, and ships its own math fonts -- for details see -# :doc:`/tutorials/text/mathtext`. Thus, you can use mathematical text across +# :ref:`mathtext`. Thus, you can use mathematical text across # platforms without requiring a TeX installation. For those who have LaTeX # and dvipng installed, you can also use LaTeX to format your text and # incorporate the output directly into your display figures or saved -# postscript -- see :doc:`/tutorials/text/usetex`. +# postscript -- see :ref:`usetex`. # # # Annotating text diff --git a/galleries/users_explain/animations/README.txt b/galleries/users_explain/animations/README.txt new file mode 100644 index 000000000000..a7d37a0242e6 --- /dev/null +++ b/galleries/users_explain/animations/README.txt @@ -0,0 +1,9 @@ +=========================== +Animations using Matplotlib +=========================== + +Based on its plotting functionality, Matplotlib also provides an interface to +generate animations using the `~matplotlib.animation` module. An +animation is a sequence of frames where each frame corresponds to a plot on a +`~matplotlib.figure.Figure`. This tutorial covers a general guideline on +how to create such animations and the different options available. diff --git a/galleries/tutorials/introductory/animation_tutorial.py b/galleries/users_explain/animations/animations.py similarity index 99% rename from galleries/tutorials/introductory/animation_tutorial.py rename to galleries/users_explain/animations/animations.py index 9b5754fb6e1b..b022350c8985 100644 --- a/galleries/tutorials/introductory/animation_tutorial.py +++ b/galleries/users_explain/animations/animations.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/introductory/animation_tutorial + +.. _animations: + =========================== Animations using Matplotlib =========================== diff --git a/galleries/tutorials/advanced/blitting.py b/galleries/users_explain/animations/blitting.py similarity index 99% rename from galleries/tutorials/advanced/blitting.py rename to galleries/users_explain/animations/blitting.py index 52d0f5984c78..b6e658f8a3cb 100644 --- a/galleries/tutorials/advanced/blitting.py +++ b/galleries/users_explain/animations/blitting.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/advanced/blitting + +.. _blitting: + ================================== Faster rendering by using blitting ================================== diff --git a/galleries/tutorials/intermediate/color_cycle.py b/galleries/users_explain/artists/color_cycle.py similarity index 98% rename from galleries/tutorials/intermediate/color_cycle.py rename to galleries/users_explain/artists/color_cycle.py index e1dc898f6d4c..715b75a88ff4 100644 --- a/galleries/tutorials/intermediate/color_cycle.py +++ b/galleries/users_explain/artists/color_cycle.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/color_cycle + +.. _color_cycle: + =================== Styling with cycler =================== diff --git a/galleries/tutorials/intermediate/imshow_extent.py b/galleries/users_explain/artists/imshow_extent.py similarity index 99% rename from galleries/tutorials/intermediate/imshow_extent.py rename to galleries/users_explain/artists/imshow_extent.py index 83ef00d5619b..849758689ca5 100644 --- a/galleries/tutorials/intermediate/imshow_extent.py +++ b/galleries/users_explain/artists/imshow_extent.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/imshow_extent + +.. _imshow_extent: + *origin* and *extent* in `~.Axes.imshow` ======================================== diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst new file mode 100644 index 000000000000..1b5e248d1ea7 --- /dev/null +++ b/galleries/users_explain/artists/index.rst @@ -0,0 +1,200 @@ +.. _users_artists: + +Using Artists +------------- + +Almost all objects you interact with on a Matplotlib plot are called "Artist" +(and are subclasses of the `.Artist` class). :doc:`Figure <../figure/index>` +and :doc:`Axes <../axes/index>` are Artists, and generally contain :doc:`Axis +<../axis/index>` Artists and Artists that contain data or annotation +information. + + +Creating Artists +~~~~~~~~~~~~~~~~ + +Usually we do not instantiate Artists directly, but rather use a plotting +method on `~.axes.Axes`. Some examples of plotting methods and the Artist +object they create is given below: + +========================================= ================= +Axes helper method Artist +========================================= ================= +`~.axes.Axes.annotate` - text annotations `.Annotation` +`~.axes.Axes.bar` - bar charts `.Rectangle` +`~.axes.Axes.errorbar` - error bar plots `.Line2D` and + `.Rectangle` +`~.axes.Axes.fill` - shared area `.Polygon` +`~.axes.Axes.hist` - histograms `.Rectangle` +`~.axes.Axes.imshow` - image data `.AxesImage` +`~.axes.Axes.legend` - Axes legend `.Legend` +`~.axes.Axes.plot` - xy plots `.Line2D` +`~.axes.Axes.scatter` - scatter charts `.PolyCollection` +`~.axes.Axes.text` - text `.Text` +========================================= ================= + +As an example, we can save the Line2D Artist returned from `.axes.Axes.plot`: + +.. sourcecode:: ipython + + In [209]: import matplotlib.pyplot as plt + In [210]: import matplotlib.artist as martist + In [211]: import numpy as np + + In [212]: fig, ax = plt.subplots() + In [213]: x, y = np.random.rand(2, 100) + In [214]: lines = ax.plot(x, y, '-', label='example') + In [215]: print(lines) + [] + +Note that ``plot`` returns a _list_ of lines because you can pass in multiple x, +y pairs to plot. The line has been added to the Axes, and we can retrieve the +Artist via `~.Axes.get_lines()`: + +.. sourcecode:: ipython + + In [216]: print(ax.get_lines()) + + In [217]: print(ax.get_lines()[0]) + Line2D(example) + +Changing Artist properties +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Getting the ``lines`` object gives us access to all the properties of the +Line2D object. So if we want to change the *linewidth* after the fact, we can do so using `.Artist.set`. + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5)) + x = np.arange(0, 13, 0.2) + y = np.sin(x) + lines = ax.plot(x, y, '-', label='example', linewidth=0.2, color='blue') + lines[0].set(color='green', linewidth=2) + +We can interrogate the full list of settable properties with +`matplotlib.artist.getp`: + +.. sourcecode:: ipython + + In [218]: martist.getp(lines[0]) + agg_filter = None + alpha = None + animated = False + antialiased or aa = True + bbox = Bbox(x0=0.004013842290585101, y0=0.013914221641967... + children = [] + clip_box = TransformedBbox( Bbox(x0=0.0, y0=0.0, x1=1.0, ... + clip_on = True + clip_path = None + color or c = blue + dash_capstyle = butt + dash_joinstyle = round + data = (array([0.91377845, 0.58456834, 0.36492019, 0.0379... + drawstyle or ds = default + figure = Figure(550x450) + fillstyle = full + gapcolor = None + gid = None + in_layout = True + label = example + linestyle or ls = - + linewidth or lw = 2.0 + marker = None + markeredgecolor or mec = blue + markeredgewidth or mew = 1.0 + markerfacecolor or mfc = blue + markerfacecoloralt or mfcalt = none + markersize or ms = 6.0 + markevery = None + mouseover = False + path = Path(array([[0.91377845, 0.51224793], [0.58... + path_effects = [] + picker = None + pickradius = 5 + rasterized = False + sketch_params = None + snap = None + solid_capstyle = projecting + solid_joinstyle = round + tightbbox = Bbox(x0=70.4609002763619, y0=54.321277798941786, x... + transform = CompositeGenericTransform( TransformWrapper( ... + transformed_clip_path_and_affine = (None, None) + url = None + visible = True + window_extent = Bbox(x0=70.4609002763619, y0=54.321277798941786, x... + xdata = [0.91377845 0.58456834 0.36492019 0.03796664 0.884... + xydata = [[0.91377845 0.51224793] [0.58456834 0.9820474 ] ... + ydata = [0.51224793 0.9820474 0.24469912 0.61647032 0.483... + zorder = 2 + +Note most Artists also have a distinct list of setters; e.g. +`.Line2D.set_color` or `.Line2D.set_linewidth`. + +Changing Artist data +~~~~~~~~~~~~~~~~~~~~ + +In addition to styling properties like *color* and *linewidth*, the Line2D +object has a *data* property. You can set the data after the line has been +created using `.Line2D.set_data`. This is often used for Animations, where the +same line is shown evolving over time (see :doc:`../animations/index`) + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5)) + x = np.arange(0, 13, 0.2) + y = np.sin(x) + lines = ax.plot(x, y, '-', label='example') + lines[0].set_data([x, np.cos(x)]) + +Manually adding Artists +~~~~~~~~~~~~~~~~~~~~~~~ + +Not all Artists have helper methods, or you may want to use a low-level method +for some reason. For example the `.patches.Circle` Artist does not have a +helper, but we can still create and add to an Axes using the +`.axes.Axes.add_artist` method: + +.. plot:: + :include-source: + + import matplotlib.patches as mpatches + + fig, ax = plt.subplots(figsize=(4, 2.5)) + circle = mpatches.Circle((0.5, 0.5), 0.25, ec="none") + ax.add_artist(circle) + clipped_circle = mpatches.Circle((1, 0.5), 0.125, ec="none", facecolor='C1') + ax.add_artist(clipped_circle) + ax.set_aspect(1) + +The Circle takes the center and radius of the Circle as arguments to its +constructor; optional arguments are passed as keyword arguments. + +Note that when we add an Artist manually like this, it doesn't necessarily +adjust the axis limits like most of the helper methods do, so the Artists can +be clipped, as is the case above for the ``clipped_circle`` patch. + +See :ref:`artist_reference` for other patches. + +Removing Artists +~~~~~~~~~~~~~~~~ + +Sometimes we want to remove an Artist from a figure without re-specifying the +whole figure from scratch. Most Artists have a usable *remove* method that +will remove the Artist from its Axes list. For instance ``lines[0].remove()`` +would remove the *Line2D* artist created in the example above. + +More details +~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + Concept: Automated color cycle + Concept: optimizing Artists for performance + Concept: Paths + Concept: Path effects guide + In Depth: understanding the extent keyword argument of imshow + transforms_tutorial diff --git a/galleries/tutorials/advanced/patheffects_guide.py b/galleries/users_explain/artists/patheffects_guide.py similarity index 98% rename from galleries/tutorials/advanced/patheffects_guide.py rename to galleries/users_explain/artists/patheffects_guide.py index ec396f6842ef..259261fb09d4 100644 --- a/galleries/tutorials/advanced/patheffects_guide.py +++ b/galleries/users_explain/artists/patheffects_guide.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/advance/patheffects_guide + +.. _patheffects_guide: + ================== Path effects guide ================== diff --git a/galleries/tutorials/advanced/path_tutorial.py b/galleries/users_explain/artists/paths.py similarity index 99% rename from galleries/tutorials/advanced/path_tutorial.py rename to galleries/users_explain/artists/paths.py index 82b663be61b6..d505711fd1c0 100644 --- a/galleries/tutorials/advanced/path_tutorial.py +++ b/galleries/users_explain/artists/paths.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/advanced/path_tutorial + +.. _paths: + ============= Path Tutorial ============= diff --git a/doc/users/explain/performance.rst b/galleries/users_explain/artists/performance.rst similarity index 97% rename from doc/users/explain/performance.rst rename to galleries/users_explain/artists/performance.rst index 03bff404b7ab..20ac800abad6 100644 --- a/doc/users/explain/performance.rst +++ b/galleries/users_explain/artists/performance.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/explain/performance + .. _performance: Performance @@ -18,7 +20,7 @@ For plots that have line segments (e.g. typical line plots, outlines of polygons, etc.), rendering performance can be controlled by :rc:`path.simplify` and :rc:`path.simplify_threshold`, which can be defined e.g. in the :file:`matplotlibrc` file (see -:doc:`/tutorials/introductory/customizing` for more information about +:ref:`customizing` for more information about the :file:`matplotlibrc` file). :rc:`path.simplify` is a Boolean indicating whether or not line segments are simplified at all. :rc:`path.simplify_threshold` controls how much line segments are simplified; @@ -52,7 +54,7 @@ value, change the :file:`matplotlibrc` file. Alternatively, users can create a new style for interactive plotting (with maximal simplification) and another style for publication quality plotting (with minimal simplification) and activate them as necessary. See -:doc:`/tutorials/introductory/customizing` for instructions on +:ref:`customizing` for instructions on how to perform these actions. The simplification works by iteratively merging line segments diff --git a/galleries/tutorials/advanced/transforms_tutorial.py b/galleries/users_explain/artists/transforms_tutorial.py similarity index 99% rename from galleries/tutorials/advanced/transforms_tutorial.py rename to galleries/users_explain/artists/transforms_tutorial.py index d254464c2ba8..c6e71ad111d7 100644 --- a/galleries/tutorials/advanced/transforms_tutorial.py +++ b/galleries/users_explain/artists/transforms_tutorial.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/advanced/transforms_tutorial + +.. _transforms_tutorial: + ======================== Transformations Tutorial ======================== @@ -209,7 +213,7 @@ # This is one good reason why you rarely want to work in *display* # space, but you can connect to the ``'on_draw'`` # :class:`~matplotlib.backend_bases.Event` to update *figure* -# coordinates on figure draws; see :ref:`event-handling-tutorial`. +# coordinates on figure draws; see :ref:`event-handling`. # # When you change the x or y limits of your axes, the data limits are # updated so the transformation yields a new display point. Note that diff --git a/galleries/tutorials/intermediate/arranging_axes.py b/galleries/users_explain/axes/arranging_axes.py similarity index 98% rename from galleries/tutorials/intermediate/arranging_axes.py rename to galleries/users_explain/axes/arranging_axes.py index a0d91943ee18..b37da984c6fc 100644 --- a/galleries/tutorials/intermediate/arranging_axes.py +++ b/galleries/users_explain/axes/arranging_axes.py @@ -1,5 +1,6 @@ """ .. redirect-from:: /tutorials/intermediate/gridspec +.. redirect-from:: /tutorials/intermediate/arranging_axes .. _arranging_axes: @@ -39,7 +40,7 @@ flexibility that Axes can also span rows or columns. The Axes are returned in a labelled dictionary instead of an array. See also `.Figure.subplot_mosaic` and - :doc:`/gallery/subplots_axes_and_figures/mosaic`. + :ref:`mosaic`. Sometimes it is natural to have more than one distinct group of Axes grids, in which case Matplotlib has the concept of `.SubFigure`: @@ -416,10 +417,9 @@ def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)): # More reading # ============ # -# - More details about :doc:`subplot mosaic -# `. -# - More details about :doc:`constrained layout -# `, used to align +# - More details about :ref:`subplot mosaic `. +# - More details about :ref:`constrained layout +# `, used to align # spacing in most of these examples. # # .. admonition:: References diff --git a/galleries/tutorials/intermediate/autoscale.py b/galleries/users_explain/axes/autoscale.py similarity index 98% rename from galleries/tutorials/intermediate/autoscale.py rename to galleries/users_explain/axes/autoscale.py index 95a157548804..fef68f2515d9 100644 --- a/galleries/tutorials/intermediate/autoscale.py +++ b/galleries/users_explain/axes/autoscale.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/autoscale + +.. _autoscale: + Autoscaling =========== diff --git a/galleries/examples/subplots_axes_and_figures/colorbar_placement.py b/galleries/users_explain/axes/colorbar_placement.py similarity index 97% rename from galleries/examples/subplots_axes_and_figures/colorbar_placement.py rename to galleries/users_explain/axes/colorbar_placement.py index f9eef05368c9..de767a4fa130 100644 --- a/galleries/examples/subplots_axes_and_figures/colorbar_placement.py +++ b/galleries/users_explain/axes/colorbar_placement.py @@ -1,6 +1,8 @@ """ .. _colorbar_placement: +.. redirect-from:: /gallery/subplots_axes_and_figures/colorbar_placement + ================= Placing Colorbars ================= diff --git a/galleries/tutorials/intermediate/constrainedlayout_guide.py b/galleries/users_explain/axes/constrainedlayout_guide.py similarity index 99% rename from galleries/tutorials/intermediate/constrainedlayout_guide.py rename to galleries/users_explain/axes/constrainedlayout_guide.py index cb4c639f198b..0a2752674c6a 100644 --- a/galleries/tutorials/intermediate/constrainedlayout_guide.py +++ b/galleries/users_explain/axes/constrainedlayout_guide.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/intermediate/constrainedlayout_guide + +.. _constrainedlayout_guide: + ================================ Constrained Layout Guide ================================ @@ -9,8 +14,8 @@ labels, legends, and colorbars do not overlap, while still preserving the logical layout requested by the user. -*Constrained layout* is similar to :doc:`Tight -layout`, but is substantially more +*Constrained layout* is similar to :ref:`Tight +layout`, but is substantially more flexible. It handles colorbars placed on multiple Axes (:ref:`colorbar_placement`) nested layouts (`~.Figure.subfigures`) and Axes that span rows or columns (`~.pyplot.subplot_mosaic`), striving to align spines from diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst new file mode 100644 index 000000000000..8bcf51add979 --- /dev/null +++ b/galleries/users_explain/axes/index.rst @@ -0,0 +1,191 @@ +################## +Axes (or Subplots) +################## + + +Matplotlib `~.axes.Axes` are the gateway to creating your data visualizations. +Once an Axes is placed on a figure there are many methods that can be used to +add data to the Axes. An Axes typically has a pair of :doc:`Axis <../axis/index>` +Artists that define the data coordinate system, and include methods to add +annotations like x- and y-labels, titles, and legends. + +.. _anatomy_local: + +.. figure:: /_static/anatomy.png + :width: 80% + + Anatomy of a Figure + +In the picture above, the Axes object was created with ``ax = fig.subplots()``. +Everything else on the figure was created with methods on this ``ax`` object, +or can be accessed from it. If we want to change the label on the x-axis, we +call ``ax.set_xlabel('New Label')``, if we want to plot some data we call +``ax.plot(x, y)``. Indeed, in the figure above, the only Artist that is not +part of the Axes is the Figure itself, so the `.axes.Axes` class is really the +gateway to much of Matplotlib's functionality. + +Note that Axes are so fundamental to the operation of Matplotlib that a lot of +material here is duplicate of that in :ref:`quick_start`. + +Creating Axes +------------- + +.. plot:: + :include-source: + + import matplotlib.pyplot as plt + import numpy as np + + fig, axs = plt.subplots(ncols=2, nrows=2, figsize=(3.5, 2.5), + layout="constrained") + # for each Axes, add an artist, in this case a nice label in the middle... + for row in range(2): + for col in range(2): + axs[row, col].annotate(f'axs[{row}, {col}]', (0.5, 0.5), + transform=axs[row, col].transAxes, + ha='center', va='center', fontsize=18, + color='darkgrey') + fig.suptitle('plt.subplots()') + + +Axes are added using methods on `~.Figure` objects, or via the `~.pyplot` interface. These methods are discussed in more detail in :ref:`creating_figures` and :doc:`arranging_axes`. However, for instance `~.Figure.add_axes` will manually position an Axes on the page. In the example above `~.pyplot.subplots` put a grid of subplots on the figure, and ``axs`` is a (2, 2) array of Axes, each of which can have data added to them. + +There are a number of other methods for adding Axes to a Figure: + +* `.Figure.add_axes`: manually position an Axes. ``fig.add_axes([0, 0, 1, + 1])`` makes an Axes that fills the whole figure. +* `.pyplot.subplots` and `.Figure.subplots`: add a grid of Axes as in the example + above. The pyplot version returns both the Figure object and an array of + Axes. Note that ``fig, ax = plt.subplots()`` adds a single Axes to a Figure. +* `.pyplot.subplot_mosaic` and `.Figure.subplot_mosaic`: add a grid of named + Axes and return a dictionary of axes. For ``fig, axs = + plt.subplot_mosaic([['left', 'right'], ['bottom', 'bottom']])``, + ``axs['left']`` is an Axes in the top row on the left, and ``axs['bottom']`` + is an Axes that spans both columns on the bottom. + +See :doc:`arranging_axes` for more detail on how to arrange grids of Axes on a +Figure. + + +Axes plotting methods +--------------------- + +Most of the high-level plotting methods are accessed from the `.axes.Axes` +class. See the API documentation for a full curated list, and +:ref:`plot_types` for examples. A basic example is `.axes.Axes.plot`: + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 3)) + np.random.seed(19680801) + t = np.arange(100) + x = np.cumsum(np.random.randn(100)) + lines = ax.plot(t, x) + +Note that ``plot`` returns a list of *lines* Artists which can subsequently be +manipulated, as discussed in :ref:`users_artists`. + +A very incomplete list of plotting methods is below. Again, see :ref:`plot_types` +for more examples, and `.axes.Axes` for the full list of methods. + +========================= ================================================== +:ref:`basic_plots` `~.axes.Axes.plot`, `~.axes.Axes.scatter`, + `~.axes.Axes.bar`, `~.axes.Axes.step`, +:ref:`arrays` `~.axes.Axes.pcolormesh`, `~.axes.Axes.contour`, + `~.axes.Axes.quiver`, `~.axes.Axes.streamplot`, + `~.axes.Axes.imshow` +:ref:`stats_plots` `~.axes.Axes.hist`, `~.axes.Axes.errorbar`, + `~.axes.Axes.hist2d`, `~.axes.Axes.pie`, + `~.axes.Axes.boxplot`, `~.axes.Axes.violinplot` +:ref:`unstructured_plots` `~.axes.Axes.tricontour`, `~.axes.Axes.tripcolor` +========================= ================================================== + +Axes labelling and annotation +----------------------------- + +Usually we want to label the Axes with an xlabel, ylabel, and title, and often we want to have a legend to differentiate plot elements. The `~.axes.Axes` class has a number of methods to create these annotations. + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(5, 3), layout='constrained') + np.random.seed(19680801) + t = np.arange(200) + x = np.cumsum(np.random.randn(200)) + y = np.cumsum(np.random.randn(200)) + linesx = ax.plot(t, x, label='Random walk x') + linesy = ax.plot(t, y, label='Random walk y') + + ax.set_xlabel('Time [s]') + ax.set_ylabel('Distance [km]') + ax.set_title('Random walk example') + ax.legend() + +These methods are relatively straight-forward, though there are a number of :ref:`text_props` that can be set on the text objects, like *fontsize*, *fontname*, *horizontalalignment*. Legends can be much more complicated; see :ref:`legend_guide` for more details. + +Note that text can also be added to axes using `~.axes.Axes.text`, and `~.axes.Axes.annotate`. This can be quite sophisticated: see :ref:`text_props` and :ref:`annotations` for more information. + + +Axes limits, scales, and ticking +-------------------------------- + +Each Axes has two (or more) `~.axis.Axis` objects, that can be accessed via :attr:`~matplotlib.axes.Axes.xaxis` and :attr:`~matplotlib.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read more about that API (:doc:`../axis/index`). However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the `~.axes.Axes.set_xlabel`, discussed above, is a helper for the `~.Axis.set_label_text`. + +Other important methods set the extent on the axes (`~.axes.Axes.set_xlim`, `~.axes.Axes.set_ylim`), or more fundamentally the scale of the axes. So for instance, we can make an Axis have a logarithmic scale, and zoom in on a sub-portion of the data: + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5), layout='constrained') + np.random.seed(19680801) + t = np.arange(200) + x = 2**np.cumsum(np.random.randn(200)) + linesx = ax.plot(t, x) + ax.set_yscale('log') + ax.set_xlim([20, 180]) + +The Axes class also has helpers to deal with Axis ticks and their labels. Most straight-forward is `~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks` which manually set the tick locations and optionally their labels. Minor ticks can be toggled with `~.axes.Axes.minorticks_on` or `~.axes.Axes.minorticks_off`. + +Many aspects of Axes ticks and tick labeling can be adjusted using `~.axes.Axes.tick_params`. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green: + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5)) + ax.plot(np.arange(10)) + ax.tick_params(top=True, labeltop=True, color='red', axis='x', + labelcolor='green') + + +More fine-grained control on ticks, setting scales, and controlling the Axis can be highly customized beyond these Axes-level helpers. An introduction to these methods can be found in :ref:`users_axis`, or the API reference for `.axis.Axis`. + +Axes layout +----------- + +Sometimes it is important to set the aspect ratio of a plot in data space, which we can do with `~.axes.Axes.set_aspect`: + +.. plot:: + :include-source: + + fig, axs = plt.subplots(ncols=2, figsize=(7, 2.5), layout='constrained') + np.random.seed(19680801) + t = np.arange(200) + x = np.cumsum(np.random.randn(200)) + axs[0].plot(t, x) + axs[0].set_title('aspect="auto"') + + axs[1].plot(t, x) + axs[1].set_aspect(3) + axs[1].set_title('aspect=3') + +.. toctree:: + :maxdepth: 1 + + arranging_axes + colorbar_placement + In depth: Autoscaling axes + In depth: Legends + In depth: Subplot mosaic + In depth: Constrained layout guide + In depth: Tight layout guide (mildly discouraged) diff --git a/galleries/tutorials/intermediate/legend_guide.py b/galleries/users_explain/axes/legend_guide.py similarity index 99% rename from galleries/tutorials/intermediate/legend_guide.py rename to galleries/users_explain/axes/legend_guide.py index 5c83ec57d0d3..9900b0aa4bdd 100644 --- a/galleries/tutorials/intermediate/legend_guide.py +++ b/galleries/users_explain/axes/legend_guide.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/legend_guide + +.. _legend_guide: + ============ Legend guide ============ @@ -11,7 +15,6 @@ :func:`~matplotlib.pyplot.legend` - please ensure you are familiar with contents of that documentation before proceeding with this guide. - This guide makes use of some common terms, which are documented here for clarity: diff --git a/galleries/examples/subplots_axes_and_figures/mosaic.py b/galleries/users_explain/axes/mosaic.py similarity index 98% rename from galleries/examples/subplots_axes_and_figures/mosaic.py rename to galleries/users_explain/axes/mosaic.py index b0a5bd1bec9a..88d4562c7af6 100644 --- a/galleries/examples/subplots_axes_and_figures/mosaic.py +++ b/galleries/users_explain/axes/mosaic.py @@ -1,7 +1,8 @@ """ .. redirect-from:: /tutorials/provisional/mosaic +.. redirect-from:: /gallery/subplots_axes_and_figures/mosaic - +.. _mosaic: ======================================================== Complex and semantic figure composition (subplot_mosaic) @@ -11,7 +12,7 @@ and verbose. For dense, even grids we have `.Figure.subplots` but for more complex layouts, such as Axes that span multiple columns / rows of the layout or leave some areas of the Figure blank, you can use -`.gridspec.GridSpec` (see :doc:`/tutorials/intermediate/arranging_axes`) or +`.gridspec.GridSpec` (see :ref:`arranging_axes`) or manually place your axes. `.Figure.subplot_mosaic` aims to provide an interface to visually lay out your axes (as either ASCII art or nested lists) to streamline this process. diff --git a/galleries/tutorials/intermediate/tight_layout_guide.py b/galleries/users_explain/axes/tight_layout_guide.py similarity index 97% rename from galleries/tutorials/intermediate/tight_layout_guide.py rename to galleries/users_explain/axes/tight_layout_guide.py index 60c3720b52a7..42c227b2e360 100644 --- a/galleries/tutorials/intermediate/tight_layout_guide.py +++ b/galleries/users_explain/axes/tight_layout_guide.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorial/intermediate/tight_layout_guide + +.. _tight_layout_guide: + ================== Tight Layout guide ================== @@ -10,8 +14,8 @@ feature and may not work for some cases. It only checks the extents of ticklabels, axis labels, and titles. -An alternative to *tight_layout* is :doc:`constrained_layout -`. +An alternative to *tight_layout* is :ref:`constrained_layout +`. Simple Example @@ -117,7 +121,7 @@ def example_plot(ax, fontsize=12): # %% # It works with subplots created with # :func:`~matplotlib.pyplot.subplot2grid`. In general, subplots created -# from the gridspec (:doc:`/tutorials/intermediate/arranging_axes`) will work. +# from the gridspec (:ref:`arranging_axes`) will work. plt.close('all') fig = plt.figure() diff --git a/galleries/users_explain/axis/index.rst b/galleries/users_explain/axis/index.rst new file mode 100644 index 000000000000..e6b8b81c8018 --- /dev/null +++ b/galleries/users_explain/axis/index.rst @@ -0,0 +1,6 @@ +.. _users_axis: + +Controlling and labelling Axis objects +-------------------------------------- + +Some good material in artist tutorial that should be cribbed from or used here. diff --git a/galleries/tutorials/colors/README.txt b/galleries/users_explain/colors/README.txt similarity index 88% rename from galleries/tutorials/colors/README.txt rename to galleries/users_explain/colors/README.txt index e25b52994c52..79f49c523f56 100644 --- a/galleries/tutorials/colors/README.txt +++ b/galleries/users_explain/colors/README.txt @@ -1,5 +1,7 @@ .. _tutorials-colors: +.. redirect-from:: /tutorials/colors/index + Colors ------ diff --git a/galleries/tutorials/colors/colorbar_only.py b/galleries/users_explain/colors/colorbar_only.py similarity index 98% rename from galleries/tutorials/colors/colorbar_only.py rename to galleries/users_explain/colors/colorbar_only.py index 62e786da3e5e..f9f126533a16 100644 --- a/galleries/tutorials/colors/colorbar_only.py +++ b/galleries/users_explain/colors/colorbar_only.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/colors/colorbar_only + ============================= Customized Colorbars Tutorial ============================= diff --git a/galleries/tutorials/colors/colormap-manipulation.py b/galleries/users_explain/colors/colormap-manipulation.py similarity index 98% rename from galleries/tutorials/colors/colormap-manipulation.py rename to galleries/users_explain/colors/colormap-manipulation.py index cd8094fe0e34..88e4c5befaf0 100644 --- a/galleries/tutorials/colors/colormap-manipulation.py +++ b/galleries/users_explain/colors/colormap-manipulation.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/colors/colormap-manipulation + +.. _colormap-manipulation: + ******************************** Creating Colormaps in Matplotlib ******************************** @@ -24,7 +28,7 @@ ============================================ First, getting a named colormap, most of which are listed in -:doc:`/tutorials/colors/colormaps`, may be done using `.matplotlib.colormaps`, +:ref:`colormaps`, may be done using `.matplotlib.colormaps`, which returns a colormap object. The length of the list of colors used internally to define the colormap can be adjusted via `.Colormap.resampled`. Below we use a modest value of 8 so there are not a lot of values to look at. @@ -115,7 +119,7 @@ def plot_examples(colormaps): # %% # In fact, that list may contain any valid -# :doc:`Matplotlib color specification `. +# :ref:`Matplotlib color specification `. # Particularly useful for creating custom colormaps are (N, 4)-shaped arrays. # Because with the variety of numpy operations that we can do on a such an # array, carpentry of new colormaps from existing colormaps become quite diff --git a/galleries/tutorials/colors/colormapnorms.py b/galleries/users_explain/colors/colormapnorms.py similarity index 99% rename from galleries/tutorials/colors/colormapnorms.py rename to galleries/users_explain/colors/colormapnorms.py index 86fea0415fac..f375b3af805b 100644 --- a/galleries/tutorials/colors/colormapnorms.py +++ b/galleries/users_explain/colors/colormapnorms.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/colors/colormapnorms + +.. _colormapnorms: + Colormap Normalization ====================== diff --git a/galleries/tutorials/colors/colormaps.py b/galleries/users_explain/colors/colormaps.py similarity index 99% rename from galleries/tutorials/colors/colormaps.py rename to galleries/users_explain/colors/colormaps.py index 68f21ee1dd37..a38dd2af0fc9 100644 --- a/galleries/tutorials/colors/colormaps.py +++ b/galleries/users_explain/colors/colormaps.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/colors/colormaps + +.. _colormaps: + ******************************** Choosing Colormaps in Matplotlib ******************************** @@ -9,7 +13,7 @@ `Third-party colormaps`_ section of the Matplotlib documentation. Here we briefly discuss how to choose between the many options. For help on creating your own colormaps, see -:doc:`/tutorials/colors/colormap-manipulation`. +:ref:`colormap-manipulation`. Overview ======== diff --git a/galleries/tutorials/colors/colors.py b/galleries/users_explain/colors/colors.py similarity index 98% rename from galleries/tutorials/colors/colors.py rename to galleries/users_explain/colors/colors.py index 62328743a09d..bd8cdb299a85 100644 --- a/galleries/tutorials/colors/colors.py +++ b/galleries/users_explain/colors/colors.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/colors/colors + +.. _colors_def: + ***************** Specifying colors ***************** @@ -127,7 +131,7 @@ # ==================== # # Matplotlib converts "CN" colors to RGBA when drawing Artists. The -# :doc:`/tutorials/intermediate/color_cycle` section contains additional +# :ref:`color_cycle` section contains additional # information about controlling colors and style properties. diff --git a/galleries/tutorials/introductory/customizing.py b/galleries/users_explain/customizing.py similarity index 99% rename from galleries/tutorials/introductory/customizing.py rename to galleries/users_explain/customizing.py index 4de4246f6eb9..58eccbcfa960 100644 --- a/galleries/tutorials/introductory/customizing.py +++ b/galleries/users_explain/customizing.py @@ -1,5 +1,8 @@ """ .. redirect-from:: /users/customizing +.. redirect-from:: /tutorials/introductory/customizing + +.. _customizing: ===================================================== Customizing Matplotlib with style sheets and rcParams diff --git a/doc/users/explain/api_interfaces.rst b/galleries/users_explain/figure/api_interfaces.rst similarity index 100% rename from doc/users/explain/api_interfaces.rst rename to galleries/users_explain/figure/api_interfaces.rst diff --git a/doc/users/explain/backends.rst b/galleries/users_explain/figure/backends.rst similarity index 98% rename from doc/users/explain/backends.rst rename to galleries/users_explain/figure/backends.rst index 9b188048de50..97e1239b8cfe 100644 --- a/doc/users/explain/backends.rst +++ b/galleries/users_explain/figure/backends.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/explain/backends + .. _backends: ======== @@ -59,7 +61,7 @@ Here is a detailed description of the configuration methods: backend : qtagg # use pyqt with antigrain (agg) rendering - See also :doc:`/tutorials/introductory/customizing`. + See also :ref:`customizing`. #. Setting the :envvar:`MPLBACKEND` environment variable: @@ -238,5 +240,4 @@ methods above. If ``name.of.the.backend`` is the module containing the backend, use ``module://name.of.the.backend`` as the backend name, e.g. ``matplotlib.use('module://name.of.the.backend')``. -Information for backend implementers is available at -:doc:`/users/explain/writing_a_backend_pyplot_interface`. +Information for backend implementers is available at :ref:`writing_backend_interface`. diff --git a/doc/users/explain/event_handling.rst b/galleries/users_explain/figure/event_handling.rst similarity index 99% rename from doc/users/explain/event_handling.rst rename to galleries/users_explain/figure/event_handling.rst index c7fe7f5ea38d..f72b9d96262f 100644 --- a/doc/users/explain/event_handling.rst +++ b/galleries/users_explain/figure/event_handling.rst @@ -1,6 +1,7 @@ .. redirect-from:: /users/event_handling -.. _event-handling-tutorial: +.. _event-handling: +.. _event_handling: ************************** Event handling and picking diff --git a/doc/users/explain/figures.rst b/galleries/users_explain/figure/index.rst similarity index 93% rename from doc/users/explain/figures.rst rename to galleries/users_explain/figure/index.rst index 4add236f370c..5e2ecc17d2c1 100644 --- a/doc/users/explain/figures.rst +++ b/galleries/users_explain/figure/index.rst @@ -1,9 +1,10 @@ +.. redirect-from:: /users/explain/figure .. _figure_explanation: -================================================ -Creating, viewing, and saving Matplotlib Figures -================================================ ++++++++++++++++++ +Figures ++++++++++++++++++ .. plot:: :include-source: @@ -22,6 +23,9 @@ multiple Axes to the Figure, colorbars, legends, annotations, and the Axes themselves can have multiple Artists added to them (e.g. ``ax.plot`` or ``ax.imshow``). +.. contents:: :local: + + .. _viewing_figures: Viewing Figures @@ -42,6 +46,7 @@ Notebooks and IDEs generated via the default `inline `_ backend. + If you are using a Notebook (e.g. `Jupyter `_) or an IDE that renders Notebooks (PyCharm, VSCode, etc), then they have a backend that will render the Matplotlib Figure when a code cell is executed. One thing to @@ -106,7 +111,7 @@ Creating Figures ================ By far the most common way to create a figure is using the -:doc:`pyplot ` interface. As noted in +:ref:`pyplot ` interface. As noted in :ref:`api_interfaces`, the pyplot interface serves two purposes. One is to spin up the Backend and keep track of GUI windows. The other is a global state for Axes and Artists that allow a short-form API to plotting methods. In the @@ -181,9 +186,9 @@ figure in expected ways, with *frameon* making the figure transparent if set to Finally, the user can specify a layout engine for the figure with the *layout* parameter. Currently Matplotlib supplies -:doc:`"constrained" `, +:ref:`"constrained" `, :ref:`"compressed" ` and -:doc:`"tight" ` layout engines. These +:ref:`"tight" ` layout engines. These rescale axes inside the Figure to prevent overlap of ticklabels, and try and align axes, and can save significant manual adjustment of artists on a Figure for many common cases. @@ -204,7 +209,7 @@ usually with care being taken to use the appropriate transform. Usually these include ``Figure.transFigure`` which ranges from 0 to 1 in each direction, and represents the fraction of the current Figure size, or ``Figure.dpi_scale_trans`` which will be in physical units of inches from the bottom left corner of the Figure -(see :doc:`/tutorials/advanced/transforms_tutorial` for more details). +(see :ref:`transforms_tutorial` for more details). .. _saving_figures: @@ -249,3 +254,17 @@ would be saved if ``bbox_inches='tight'`` were used in savefig. ec=(0, 0.0, 0, 0.5), lw=2, linestyle='--', transform=None, clip_on=False) ax.add_patch(fancy) + + +More reading +============ + +.. toctree:: + :maxdepth: 1 + + Concept: Output backends + Concept: Matplotlib Application Interfaces (APIs) + In depth: Interacting with figures + In depth: Interactive figures and asynchronous programming + In depth: Event handling + In depth: Writing a backend -- the pyplot interface diff --git a/doc/users/explain/interactive.rst b/galleries/users_explain/figure/interactive.rst similarity index 98% rename from doc/users/explain/interactive.rst rename to galleries/users_explain/figure/interactive.rst index 942b682fb04c..5422fa47bfd2 100644 --- a/doc/users/explain/interactive.rst +++ b/galleries/users_explain/figure/interactive.rst @@ -1,4 +1,5 @@ .. redirect-from:: /users/interactive +.. redirect-from:: /users/explain/interactive .. currentmodule:: matplotlib @@ -52,7 +53,7 @@ collected. `.Figure`\s can be closed and deregistered from `.pyplot` individuall For more discussion of Matplotlib's event system and integrated event loops: - :ref:`interactive_figures_and_eventloops` - - :ref:`event-handling-tutorial` + - :ref:`event-handling` .. _ipython-pylab: @@ -210,8 +211,8 @@ Navigation keyboard shortcuts ----------------------------- The following table holds all the default keys, which can be -overwritten by use of your :doc:`matplotlibrc -`. +overwritten by use of your :ref:`matplotlibrc +`. ================================== =============================== Command Default key binding and rcParam diff --git a/doc/users/explain/interactive_guide.rst b/galleries/users_explain/figure/interactive_guide.rst similarity index 99% rename from doc/users/explain/interactive_guide.rst rename to galleries/users_explain/figure/interactive_guide.rst index 9c110967d94a..39f5402708b7 100644 --- a/doc/users/explain/interactive_guide.rst +++ b/galleries/users_explain/figure/interactive_guide.rst @@ -18,7 +18,7 @@ you can use to build sophisticated interactive graphs. This guide is meant to be an introduction to the low-level details of how Matplotlib integration with a GUI event loop works. For a more practical introduction to the Matplotlib event API see :ref:`event -handling system `, `Interactive Tutorial +handling system `, `Interactive Tutorial `__, and `Interactive Applications using Matplotlib `__. @@ -64,7 +64,7 @@ capturing user interactions and passing them back to the application details depend on the toolkit. Matplotlib has a :ref:`backend ` for each GUI toolkit we support which uses the toolkit API to bridge the toolkit UI events into Matplotlib's :ref:`event -handling system `. You can then use +handling system `. You can then use `.FigureCanvasBase.mpl_connect` to connect your function to Matplotlib's event handling system. This allows you to directly interact with your data and write GUI toolkit agnostic user diff --git a/doc/users/explain/writing_a_backend_pyplot_interface.rst b/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst similarity index 96% rename from doc/users/explain/writing_a_backend_pyplot_interface.rst rename to galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst index e193135f970d..452f4d7610bb 100644 --- a/doc/users/explain/writing_a_backend_pyplot_interface.rst +++ b/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst @@ -1,9 +1,13 @@ +.. redirect-from:: /users/explain/writing_a_backend_pyplot_interface + +.. _writing_backend_interface: + ========================================= Writing a backend -- the pyplot interface ========================================= This page assumes general understanding of the information in the -:doc:`/users/explain/backends` page, and is instead intended as reference for +:ref:`backends` page, and is instead intended as reference for third-party backend implementers. It also only deals with the interaction between backends and `.pyplot`, not with the rendering side, which is described in `.backend_template`. diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst new file mode 100644 index 000000000000..56b7004b18be --- /dev/null +++ b/galleries/users_explain/index.rst @@ -0,0 +1,21 @@ +.. _users-guide-explain: +.. _users-guide-using: + +.. redirect-from:: /users/explain + +Using Matplotlib +---------------- + +.. toctree:: + :maxdepth: 1 + + quick_start + figure/index + axes/index + artists/index + customizing + axis/index + colors/index + text/index + animations/index + toolkits/index diff --git a/galleries/tutorials/introductory/quick_start.py b/galleries/users_explain/quick_start.py similarity index 95% rename from galleries/tutorials/introductory/quick_start.py rename to galleries/users_explain/quick_start.py index 0c34ca639bba..e203d042f74a 100644 --- a/galleries/tutorials/introductory/quick_start.py +++ b/galleries/users_explain/quick_start.py @@ -1,4 +1,9 @@ """ +.. redirect-from:: /tutorials/introductory/usage +.. redirect-from:: /tutorials/introductory/quick_start + +.. _quick_start: + ***************** Quick start guide ***************** @@ -6,8 +11,6 @@ This tutorial covers some basic usage patterns and best practices to help you get started with Matplotlib. -.. redirect-from:: /tutorials/introductory/usage - """ import matplotlib.pyplot as plt @@ -65,7 +68,7 @@ # # It is often convenient to create the Axes together with the Figure, but you # can also manually add Axes later on. Note that many -# :doc:`Matplotlib backends ` support zooming and +# :ref:`Matplotlib backends ` support zooming and # panning on figure windows. # # For more on Figures, see :ref:`figure_explanation`. @@ -253,7 +256,7 @@ def my_plotter(ax, data1, data2, param_dict): # ------ # # Matplotlib has a very flexible array of colors that are accepted for most -# Artists; see the :doc:`colors tutorial ` for a +# Artists; see :ref:`allowable color definitions ` for a # list of specifications. Some Artists will take multiple colors. i.e. for # a `~.Axes.scatter` plot, the edge of the markers can be different colors # from the interior: @@ -294,7 +297,7 @@ def my_plotter(ax, data1, data2, param_dict): # -------------------- # # `~.Axes.set_xlabel`, `~.Axes.set_ylabel`, and `~.Axes.set_title` are used to -# add text in the indicated locations (see :doc:`/tutorials/text/text_intro` +# add text in the indicated locations (see :ref:`text_intro` # for more discussion). Text can also be directly added to plots using # `~.Axes.text`: @@ -319,7 +322,7 @@ def my_plotter(ax, data1, data2, param_dict): # t = ax.set_xlabel('my data', fontsize=14, color='red') # # These properties are covered in more detail in -# :doc:`/tutorials/text/text_props`. +# :ref:`text_props`. # # Using mathematical expressions in text # -------------------------------------- @@ -334,9 +337,9 @@ def my_plotter(ax, data1, data2, param_dict): # *raw* string and not to treat backslashes as python escapes. # Matplotlib has a built-in TeX expression parser and # layout engine, and ships its own math fonts – for details see -# :doc:`/tutorials/text/mathtext`. You can also use LaTeX directly to format +# :ref:`mathtext`. You can also use LaTeX directly to format # your text and incorporate the output directly into your display figures or -# saved postscript – see :doc:`/tutorials/text/usetex`. +# saved postscript – see :ref:`usetex`. # # Annotations # ----------- @@ -376,7 +379,7 @@ def my_plotter(ax, data1, data2, param_dict): # %% # Legends in Matplotlib are quite flexible in layout, placement, and what # Artists they can represent. They are discussed in detail in -# :doc:`/tutorials/intermediate/legend_guide`. +# :ref:`legend_guide`. # # Axis scales and ticks # ===================== @@ -408,7 +411,7 @@ def my_plotter(ax, data1, data2, param_dict): # The scale sets the mapping from data values to spacing along the Axis. This # happens in both directions, and gets combined into a *transform*, which # is the way that Matplotlib maps from data coordinates to Axes, Figure, or -# screen coordinates. See :doc:`/tutorials/advanced/transforms_tutorial`. +# screen coordinates. See :ref:`transforms_tutorial`. # # Tick locators and formatters # ---------------------------- @@ -528,8 +531,8 @@ def my_plotter(ax, data1, data2, param_dict): # These are all examples of Artists that derive from `~.ScalarMappable` # objects. They all can set a linear mapping between *vmin* and *vmax* into # the colormap specified by *cmap*. Matplotlib has many colormaps to choose -# from (:doc:`/tutorials/colors/colormaps`) you can make your -# own (:doc:`/tutorials/colors/colormap-manipulation`) or download as +# from (:ref:`colormaps`) you can make your +# own (:ref:`colormap-manipulation`) or download as # `third-party packages # `_. # @@ -539,7 +542,7 @@ def my_plotter(ax, data1, data2, param_dict): # Sometimes we want a non-linear mapping of the data to the colormap, as # in the ``LogNorm`` example above. We do this by supplying the # ScalarMappable with the *norm* argument instead of *vmin* and *vmax*. -# More normalizations are shown at :doc:`/tutorials/colors/colormapnorms`. +# More normalizations are shown at :ref:`colormapnorms`. # # Colorbars # --------- @@ -549,7 +552,7 @@ def my_plotter(ax, data1, data2, param_dict): # a ScalarMappable (where they get their information about the norm and # colormap) and usually steal space from a parent Axes. Placement of # colorbars can be complex: see -# :doc:`/gallery/subplots_axes_and_figures/colorbar_placement` for +# :ref:`colorbar_placement` for # details. You can also change the appearance of colorbars with the # *extend* keyword to add arrows to the ends, and *shrink* and *aspect* to # control the size. Finally, the colorbar will have default locators @@ -576,8 +579,7 @@ def my_plotter(ax, data1, data2, param_dict): # %% # Matplotlib has quite sophisticated tools for arranging Axes: See -# :doc:`/tutorials/intermediate/arranging_axes` and -# :doc:`/gallery/subplots_axes_and_figures/mosaic`. +# :ref:`arranging_axes` and :ref:`mosaic`. # # # More reading diff --git a/galleries/tutorials/text/README.txt b/galleries/users_explain/text/README.txt similarity index 89% rename from galleries/tutorials/text/README.txt rename to galleries/users_explain/text/README.txt index 4eaaa4de9c23..8fe69bc0dba7 100644 --- a/galleries/tutorials/text/README.txt +++ b/galleries/users_explain/text/README.txt @@ -1,3 +1,5 @@ +.. redirect-from:: /tutorials/text + .. _tutorials-text: Text diff --git a/galleries/tutorials/text/annotations.py b/galleries/users_explain/text/annotations.py similarity index 96% rename from galleries/tutorials/text/annotations.py rename to galleries/users_explain/text/annotations.py index b7a1807f6c33..5864d2c3a997 100644 --- a/galleries/tutorials/text/annotations.py +++ b/galleries/users_explain/text/annotations.py @@ -6,6 +6,9 @@ .. redirect-from:: /gallery/userdemo/anchored_box04 .. redirect-from:: /gallery/userdemo/annotate_simple_coord01 .. redirect-from:: /gallery/userdemo/annotate_simple_coord03 +.. redirect-from:: /tutorials/text/annotations + +.. _annotations: Annotations =========== @@ -236,8 +239,8 @@ # Square ``square`` pad=0.3 # ========== ============== ========================== # -# .. figure:: ../../gallery/shapes_and_collections/images/sphx_glr_fancybox_demo_001.png -# :target: ../../gallery/shapes_and_collections/fancybox_demo.html +# .. figure:: /gallery/shapes_and_collections/images/sphx_glr_fancybox_demo_001.png +# :target: /gallery/shapes_and_collections/fancybox_demo.html # :align: center # # The patch object (box) associated with the text can be accessed using:: @@ -326,8 +329,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # 4. The path is transmuted to an arrow patch, as specified by the *arrowstyle* # parameter. # -# .. figure:: ../../gallery/userdemo/images/sphx_glr_annotate_explain_001.png -# :target: ../../gallery/userdemo/annotate_explain.html +# .. figure:: /gallery/userdemo/images/sphx_glr_annotate_explain_001.png +# :target: /gallery/userdemo/annotate_explain.html # :align: center # # The creation of the connecting path between two points is controlled by @@ -352,8 +355,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # example below. (Warning: The behavior of the ``bar`` style is currently not # well-defined and may be changed in the future). # -# .. figure:: ../../gallery/userdemo/images/sphx_glr_connectionstyle_demo_001.png -# :target: ../../gallery/userdemo/connectionstyle_demo.html +# .. figure:: /gallery/userdemo/images/sphx_glr_connectionstyle_demo_001.png +# :target: /gallery/userdemo/connectionstyle_demo.html # :align: center # # The connecting path (after clipping and shrinking) is then mutated to @@ -376,8 +379,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # ``wedge`` tail_width=0.3,shrink_factor=0.5 # ========== ============================================= # -# .. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_fancyarrow_demo_001.png -# :target: ../../gallery/text_labels_and_annotations/fancyarrow_demo.html +# .. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_fancyarrow_demo_001.png +# :target: /gallery/text_labels_and_annotations/fancyarrow_demo.html # :align: center # # Some arrowstyles only work with connection styles that generate a @@ -559,7 +562,7 @@ def custom_box_style(x0, y0, width, height, mutation_size): # Some others more advanced options are: # # 1. A `.Transform` instance. For more information on transforms, see the -# :doc:`../advanced/transforms_tutorial` For example, the +# :ref:`transforms_tutorial` For example, the # ``Axes.transAxes`` transform positions the annotation relative to the Axes # coordinates and using it is therefore identical to setting the # coordinate system to "axes fraction": @@ -688,8 +691,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # Here, we added the `.ConnectionPatch` to the *figure* # (with `~.Figure.add_artist`) rather than to either axes. This ensures that # the ConnectionPatch artist is drawn on top of both axes, and is also necessary -# when using :doc:`constrained_layout -# ` for positioning the axes. +# when using :ref:`constrained_layout ` +# for positioning the axes. # # Zoom effect between Axes # ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -697,11 +700,11 @@ def custom_box_style(x0, y0, width, height, mutation_size): # `mpl_toolkits.axes_grid1.inset_locator` defines some patch classes useful for # interconnecting two axes. # -# .. figure:: ../../gallery/subplots_axes_and_figures/images/sphx_glr_axes_zoom_effect_001.png -# :target: ../../gallery/subplots_axes_and_figures/axes_zoom_effect.html +# .. figure:: /gallery/subplots_axes_and_figures/images/sphx_glr_axes_zoom_effect_001.png +# :target: /gallery/subplots_axes_and_figures/axes_zoom_effect.html # :align: center # # The code for this figure is at # :doc:`/gallery/subplots_axes_and_figures/axes_zoom_effect` and -# familiarity with :doc:`../advanced/transforms_tutorial` +# familiarity with :ref:`transforms_tutorial` # is recommended. diff --git a/doc/users/explain/fonts.rst b/galleries/users_explain/text/fonts.py similarity index 93% rename from doc/users/explain/fonts.rst rename to galleries/users_explain/text/fonts.py index 1f12c5760d25..dd27f4f573d1 100644 --- a/doc/users/explain/fonts.rst +++ b/galleries/users_explain/text/fonts.py @@ -1,4 +1,8 @@ +r""" .. redirect-from:: /users/fonts +.. redirect-from:: /users/explain/fonts + +.. _fonts: Fonts in Matplotlib =================== @@ -7,13 +11,13 @@ alongside the installation. The default font is `DejaVu Sans `_ which covers most European writing systems. However, users can configure the default fonts, and provide their own custom -fonts. See :doc:`Customizing text properties ` for +fonts. See :ref:`Customizing text properties ` for details and :ref:`font-nonlatin` in particular for glyphs not supported by DejaVu Sans. Matplotlib also provides an option to offload text rendering to a TeX engine -(``usetex=True``), see :doc:`Text rendering with LaTeX -`. +(``usetex=True``), see :ref:`Text rendering with LaTeX +`. Fonts in PDF and PostScript --------------------------- @@ -41,7 +45,8 @@ - Hinting supported (virtual machine processes the "hints") * - Non-subsetted through Matplotlib - Subsetted via external module ttconv - - Subsetted via external module `fontTools `__ + - Subsetted via external module + `fontTools `__ .. note:: @@ -54,9 +59,11 @@ - Type 42 fonts (PS): - PostScript wrapper around TrueType fonts - - 42 is the `Answer to Life, the Universe, and Everything! `_ - - Matplotlib uses the external library `fontTools `__ - to subset these types of fonts + - 42 is the `Answer to Life, the Universe, and Everything! + `_ + - Matplotlib uses the external library + `fontTools `__ to subset these types of + fonts - OpenType fonts: @@ -191,3 +198,4 @@ A majority of this work was done by Aitik Gupta supported by Google Summer of Code 2021. +""" diff --git a/galleries/tutorials/text/mathtext.py b/galleries/users_explain/text/mathtext.py similarity index 97% rename from galleries/tutorials/text/mathtext.py rename to galleries/users_explain/text/mathtext.py index 2be0d67ca3b0..211d46dd50b9 100644 --- a/galleries/tutorials/text/mathtext.py +++ b/galleries/users_explain/text/mathtext.py @@ -1,4 +1,9 @@ r""" + +.. redirect-from:: /tutorials/text/mathtext + +.. _mathtext: + Writing mathematical expressions ================================ @@ -10,7 +15,7 @@ is a fairly direct adaptation of the layout algorithms in Donald Knuth's TeX, so the quality is quite good (Matplotlib also provides a ``usetex`` option for those who do want to call out to TeX to generate their text; see -:doc:`/tutorials/text/usetex`). +:ref:`usetex`). Any text element can use math text. You should use raw strings (precede the quotes with an ``'r'``), and surround the math text with dollar signs ($), as @@ -19,7 +24,7 @@ (from (La)TeX), `STIX `_ fonts (which are designed to blend well with Times), or a Unicode font that you provide. The mathtext font can be selected via :rc:`mathtext.fontset` (see -:doc:`/tutorials/introductory/customizing`) +:ref:`customizing`) Here is a simple example:: @@ -50,7 +55,7 @@ have special meaning outside of math mode in TeX. Therefore, these characters will behave differently depending on :rc:`text.usetex`. See the - :doc:`usetex tutorial ` for more information. + :ref:`usetex tutorial ` for more information. Subscripts and superscripts --------------------------- @@ -354,7 +359,7 @@ ------- Here is an example illustrating many of these features in context. -.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_mathtext_demo_001.png - :target: ../../gallery/text_labels_and_annotations/mathtext_demo.html +.. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_mathtext_demo_001.png + :target: /gallery/text_labels_and_annotations/mathtext_demo.html :align: center """ diff --git a/galleries/tutorials/text/pgf.py b/galleries/users_explain/text/pgf.py similarity index 96% rename from galleries/tutorials/text/pgf.py rename to galleries/users_explain/text/pgf.py index 5cbf4cfa8b98..5dfd7e53f4a0 100644 --- a/galleries/tutorials/text/pgf.py +++ b/galleries/users_explain/text/pgf.py @@ -1,4 +1,9 @@ r""" + +.. redirect-from:: /tutorials/text/pgf + +.. _pgf: + ************************************************************ Text rendering with XeLaTeX/LuaLaTeX via the ``pgf`` backend ************************************************************ @@ -100,7 +105,7 @@ When saving to ``.pgf``, the font configuration Matplotlib used for the layout of the figure is included in the header of the text file. -.. literalinclude:: ../../gallery/userdemo/pgf_fonts.py +.. literalinclude:: /gallery/userdemo/pgf_fonts.py :end-before: fig.savefig @@ -117,12 +122,12 @@ .. only:: html - .. literalinclude:: ../../gallery/userdemo/pgf_preamble_sgskip.py + .. literalinclude:: /gallery/userdemo/pgf_preamble_sgskip.py :end-before: fig.savefig .. only:: latex - .. literalinclude:: ../../gallery/userdemo/pgf_preamble_sgskip.py + .. literalinclude:: /gallery/userdemo/pgf_preamble_sgskip.py :end-before: import matplotlib.pyplot as plt @@ -136,7 +141,7 @@ Please note that when selecting pdflatex, the fonts and Unicode handling must be configured in the preamble. -.. literalinclude:: ../../gallery/userdemo/pgf_texsystem.py +.. literalinclude:: /gallery/userdemo/pgf_texsystem.py :end-before: fig.savefig diff --git a/galleries/tutorials/text/text_intro.py b/galleries/users_explain/text/text_intro.py similarity index 98% rename from galleries/tutorials/text/text_intro.py rename to galleries/users_explain/text/text_intro.py index 10aae0f40887..eccd584ce36f 100644 --- a/galleries/tutorials/text/text_intro.py +++ b/galleries/users_explain/text/text_intro.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/text/text_intro + +.. _text_intro: + ======================== Text in Matplotlib Plots ======================== @@ -21,11 +26,11 @@ The user has a great deal of control over text properties (font size, font weight, text location and color, etc.) with sensible defaults set in -the :doc:`rc file `. +the :ref:`rc file `. And significantly, for those interested in mathematical or scientific figures, Matplotlib implements a large number of TeX -math symbols and commands, supporting :doc:`mathematical expressions -` anywhere in your figure. +math symbols and commands, supporting :ref:`mathematical expressions +` anywhere in your figure. Basic text commands @@ -419,6 +424,6 @@ def formatoddticks(x, pos): # Legends and Annotations # ======================= # -# - Legends: :doc:`/tutorials/intermediate/legend_guide` -# - Annotations: :doc:`/tutorials/text/annotations` +# - Legends: :ref:`legend_guide` +# - Annotations: :ref:`annotations` # diff --git a/galleries/tutorials/text/text_props.py b/galleries/users_explain/text/text_props.py similarity index 97% rename from galleries/tutorials/text/text_props.py rename to galleries/users_explain/text/text_props.py index 6ac870cab263..20111f0775f5 100644 --- a/galleries/tutorials/text/text_props.py +++ b/galleries/users_explain/text/text_props.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/text/text_props + +.. _text_props: + ============================ Text properties and layout ============================ @@ -13,12 +18,12 @@ Property Value Type ========================== ====================================================================================================================== alpha `float` -backgroundcolor any matplotlib :doc:`color ` +backgroundcolor any matplotlib :ref:`color ` bbox `~matplotlib.patches.Rectangle` prop dict plus key ``'pad'`` which is a pad in points clip_box a matplotlib.transform.Bbox instance clip_on bool clip_path a `~matplotlib.path.Path` instance and a `~matplotlib.transforms.Transform` instance, a `~matplotlib.patches.Patch` -color any matplotlib :doc:`color ` +color any matplotlib :ref:`color ` family [ ``'serif'`` | ``'sans-serif'`` | ``'cursive'`` | ``'fantasy'`` | ``'monospace'`` ] fontproperties `~matplotlib.font_manager.FontProperties` horizontalalignment or ha [ ``'center'`` | ``'right'`` | ``'left'`` ] @@ -186,7 +191,7 @@ # matplotlib.font_manager.get_font_names() # # The mapping between the generic family aliases and actual font families -# (mentioned at :doc:`default rcParams `) +# (mentioned at :ref:`default rcParams `) # is controlled by the following rcParams: # # @@ -248,8 +253,7 @@ # font.family: Source Han Sans TW, Arial, sans-serif # # To control the font used on per-artist basis use the *name*, *fontname* or -# *fontproperties* keyword arguments documented :doc:`above -# `. +# *fontproperties* keyword arguments documented in :ref:`text_props`. # # # On linux, `fc-list `__ can be a diff --git a/galleries/tutorials/text/usetex.py b/galleries/users_explain/text/usetex.py similarity index 95% rename from galleries/tutorials/text/usetex.py rename to galleries/users_explain/text/usetex.py index 2b55864b18f6..0194a0030d48 100644 --- a/galleries/tutorials/text/usetex.py +++ b/galleries/users_explain/text/usetex.py @@ -1,4 +1,8 @@ r""" +.. redirect-from:: /tutorials/text/usetex + +.. _usetex: + ************************* Text rendering with LaTeX ************************* @@ -6,7 +10,7 @@ Matplotlib can use LaTeX to render text. This is activated by setting ``text.usetex : True`` in your rcParams, or by setting the ``usetex`` property to True on individual `.Text` objects. Text handling through LaTeX is slower -than Matplotlib's very capable :doc:`mathtext `, but +than Matplotlib's very capable :ref:`mathtext `, but is more flexible, since different LaTeX packages (font packages, math packages, etc.) can be used. The results can be striking, especially when you take care to use the same fonts in your figures as in the main document. @@ -51,8 +55,7 @@ "font.family": "Helvetica" }) -or equivalently, set your :doc:`matplotlibrc -` to:: +or equivalently, set your :ref:`matplotlibrc ` to:: text.usetex : true font.family : Helvetica @@ -71,8 +74,8 @@ Here is the standard example, :doc:`/gallery/text_labels_and_annotations/tex_demo`: -.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png - :target: ../../gallery/text_labels_and_annotations/tex_demo.html +.. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png + :target: /gallery/text_labels_and_annotations/tex_demo.html :align: center Note that display math mode (``$$ e=mc^2 $$``) is not supported, but adding the diff --git a/galleries/tutorials/toolkits/README.txt b/galleries/users_explain/toolkits/README.txt similarity index 80% rename from galleries/tutorials/toolkits/README.txt rename to galleries/users_explain/toolkits/README.txt index 4a0c6ab3af64..a72d8f87a43c 100644 --- a/galleries/tutorials/toolkits/README.txt +++ b/galleries/users_explain/toolkits/README.txt @@ -1,5 +1,7 @@ .. _tutorials-toolkits: +.. redirect-from:: /tutorials/toolkits + Toolkits -------- diff --git a/galleries/tutorials/toolkits/axes_grid.py b/galleries/users_explain/toolkits/axes_grid.py similarity index 84% rename from galleries/tutorials/toolkits/axes_grid.py rename to galleries/users_explain/toolkits/axes_grid.py index 0206b7ed816b..84d1ecc4d288 100644 --- a/galleries/tutorials/toolkits/axes_grid.py +++ b/galleries/users_explain/toolkits/axes_grid.py @@ -1,5 +1,8 @@ r""" +.. redirect-from:: /tutorials/toolkits/axes_grid + .. _axes_grid1_users-guide-index: +.. _axes_grid: ====================== The axes_grid1 toolkit @@ -16,8 +19,8 @@ - AnchoredArtists_ (custom artists which are placed at an anchored position, similarly to legends). -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png - :target: ../../gallery/axes_grid1/demo_axes_grid.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png + :target: /gallery/axes_grid1/demo_axes_grid.html :align: center axes_grid1 @@ -32,8 +35,8 @@ `~.axes_grid1.axes_grid.ImageGrid` can be used to achieve such a padding; see its docs for detailed API information. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid_001.png - :target: ../../gallery/axes_grid1/simple_axesgrid.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axesgrid_001.png + :target: /gallery/axes_grid1/simple_axesgrid.html :align: center * The position of each axes is determined at the drawing time (see @@ -48,14 +51,14 @@ the same row all have the same height. These widths and heights are scaled in proportion to the axes' view limits (xlim or ylim). - .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid2_001.png - :target: ../../gallery/axes_grid1/simple_axesgrid2.html + .. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axesgrid2_001.png + :target: /gallery/axes_grid1/simple_axesgrid2.html :align: center The examples below show what you can do with ImageGrid. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png - :target: ../../gallery/axes_grid1/demo_axes_grid.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png + :target: /gallery/axes_grid1/demo_axes_grid.html :align: center AxesDivider Class @@ -79,8 +82,8 @@ colorbar whose height (or width) is in sync with the main axes -------------------------------------------------------------- -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_colorbar_001.png - :target: ../../gallery/axes_grid1/simple_colorbar.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_colorbar_001.png + :target: /gallery/axes_grid1/simple_colorbar.html :align: center scatter_hist.py with AxesDivider @@ -106,8 +109,8 @@ See the full source code below. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_scatter_hist_locatable_axes_001.png - :target: ../../gallery/axes_grid1/scatter_hist_locatable_axes.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_scatter_hist_locatable_axes_001.png + :target: /gallery/axes_grid1/scatter_hist_locatable_axes.html :align: center The :doc:`/gallery/axes_grid1/scatter_hist_locatable_axes` using the @@ -141,8 +144,8 @@ Example 1: twinx ~~~~~~~~~~~~~~~~ -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple_001.png - :target: ../../gallery/axes_grid1/parasite_simple.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_parasite_simple_001.png + :target: /gallery/axes_grid1/parasite_simple.html :align: center Example 2: twin @@ -158,16 +161,16 @@ labels=["0", r"$\frac{1}{2}\pi$", r"$\pi$", r"$\frac{3}{2}\pi$", r"$2\pi$"]) -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axisline4_001.png - :target: ../../gallery/axes_grid1/simple_axisline4.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axisline4_001.png + :target: /gallery/axes_grid1/simple_axisline4.html :align: center A more sophisticated example using twin. Note that if you change the x-limit in the host axes, the x-limit of the parasite axes will change accordingly. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple2_001.png - :target: ../../gallery/axes_grid1/parasite_simple2.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_parasite_simple2_001.png + :target: /gallery/axes_grid1/parasite_simple2.html :align: center AnchoredArtists @@ -179,8 +182,8 @@ coordinates. There is limited support for arbitrary transforms. For example, the ellipse in the example below will have width and height in data coordinates. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_anchored_artists_001.png - :target: ../../gallery/axes_grid1/simple_anchored_artists.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_anchored_artists_001.png + :target: /gallery/axes_grid1/simple_anchored_artists.html :align: center InsetLocator @@ -214,15 +217,15 @@ creates an inset axes whose data scale is half of the parent axes. This can be useful to mark the zoomed area on the parent axes: -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo_001.png - :target: ../../gallery/axes_grid1/inset_locator_demo.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_inset_locator_demo_001.png + :target: /gallery/axes_grid1/inset_locator_demo.html :align: center `.inset_locator.mark_inset` allows marking the location of the area represented by the inset axes: -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo2_001.png - :target: ../../gallery/axes_grid1/inset_locator_demo2.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_inset_locator_demo2_001.png + :target: /gallery/axes_grid1/inset_locator_demo2.html :align: center RGBAxes @@ -240,8 +243,8 @@ r, g, b = get_rgb() # r, g, b are 2D images. ax.imshow_rgb(r, g, b) -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_rgb_001.png - :target: ../../gallery/axes_grid1/demo_axes_rgb.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_demo_axes_rgb_001.png + :target: /gallery/axes_grid1/demo_axes_rgb.html :align: center AxesDivider @@ -318,14 +321,14 @@ See the example, -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider1_001.png - :target: ../../gallery/axes_grid1/simple_axes_divider1.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axes_divider1_001.png + :target: /gallery/axes_grid1/simple_axes_divider1.html :align: center You can also adjust the size of each axes according to its x or y data limits (AxesX and AxesY). -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png - :target: ../../gallery/axes_grid1/simple_axes_divider3.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png + :target: /gallery/axes_grid1/simple_axes_divider3.html :align: center """ diff --git a/galleries/tutorials/toolkits/axisartist.py b/galleries/users_explain/toolkits/axisartist.py similarity index 90% rename from galleries/tutorials/toolkits/axisartist.py rename to galleries/users_explain/toolkits/axisartist.py index d05087e9f8b2..f09d0c70894e 100644 --- a/galleries/tutorials/toolkits/axisartist.py +++ b/galleries/users_explain/toolkits/axisartist.py @@ -1,4 +1,9 @@ r""" + +.. redirect-from:: /tutorials/toolkits/axisartist + +.. _axisartist: + ====================== The axisartist toolkit ====================== @@ -15,8 +20,8 @@ artist (AxisArtist) that can handle ticks, ticklines, etc. for curved coordinate systems. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png - :target: ../../gallery/axisartist/demo_floating_axis.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png + :target: /gallery/axisartist/demo_floating_axis.html :align: center Since it uses special artists, some Matplotlib commands that work on @@ -60,8 +65,8 @@ ax.axis["right"].set_visible(False) ax.axis["top"].set_visible(False) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axisline3_001.png - :target: ../../gallery/axisartist/simple_axisline3.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axisline3_001.png + :target: /gallery/axisartist/simple_axisline3.html :align: center It is also possible to add a horizontal axis. For example, you may have an @@ -69,8 +74,8 @@ ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axisartist1_001.png - :target: ../../gallery/axisartist/simple_axisartist1.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axisartist1_001.png + :target: /gallery/axisartist/simple_axisartist1.html :align: center Or a fixed axis with some offset :: @@ -92,8 +97,8 @@ Here is an example that uses ParasiteAxes. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png - :target: ../../gallery/axisartist/demo_parasite_axes2.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png + :target: /gallery/axisartist/demo_parasite_axes2.html :align: center Curvilinear Grid @@ -102,8 +107,8 @@ The motivation behind the AxisArtist module is to support a curvilinear grid and ticks. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png - :target: ../../gallery/axisartist/demo_curvelinear_grid.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png + :target: /gallery/axisartist/demo_curvelinear_grid.html :align: center Floating Axes @@ -112,8 +117,8 @@ AxisArtist also supports a Floating Axes whose outer axes are defined as floating axis. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png - :target: ../../gallery/axisartist/demo_floating_axes.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png + :target: /gallery/axisartist/demo_floating_axes.html :align: center axisartist namespace @@ -144,8 +149,8 @@ * a curvilinear grid. * a floating axis -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png - :target: ../../gallery/axisartist/demo_floating_axis.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png + :target: /gallery/axisartist/demo_floating_axis.html :align: center *mpl_toolkits.axisartist.Axes* class defines a *axis* attribute, which @@ -305,8 +310,8 @@ ax1.axis["left"].major_ticklabels.set_axis_direction("top") ax1.axis["right"].label.set_axis_direction("left") -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_direction01_001.png - :target: ../../gallery/axisartist/simple_axis_direction01.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axis_direction01_001.png + :target: /gallery/axisartist/simple_axis_direction01.html :align: center The parameter for set_axis_direction is one of ["left", "right", @@ -330,8 +335,8 @@ to the *ticklabel_direction* or *label_direction*, respectively. The rotation of ticklabels and label is anchored. -.. figure:: ../../gallery/axisartist/images/sphx_glr_axis_direction_001.png - :target: ../../gallery/axisartist/axis_direction.html +.. figure:: /gallery/axisartist/images/sphx_glr_axis_direction_001.png + :target: /gallery/axisartist/axis_direction.html :align: center On the other hand, there is a concept of "axis_direction". This is a @@ -355,8 +360,8 @@ etc, for settings suitable for "top" axis. The concept of axis direction can be more clear with curved axis. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_axis_direction_001.png - :target: ../../gallery/axisartist/demo_axis_direction.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_axis_direction_001.png + :target: /gallery/axisartist/demo_axis_direction.html :align: center The axis_direction can be adjusted in the AxisArtist level, or in the @@ -386,8 +391,8 @@ ax.axis[:].major_ticks.set_tick_out(True) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_direction03_001.png - :target: ../../gallery/axisartist/simple_axis_direction03.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axis_direction03_001.png + :target: /gallery/axisartist/simple_axis_direction03.html :align: center So, in summary, @@ -421,8 +426,8 @@ Alignment of TickLabels are treated specially. See below -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_ticklabel_alignment_001.png - :target: ../../gallery/axisartist/demo_ticklabel_alignment.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_ticklabel_alignment_001.png + :target: /gallery/axisartist/demo_ticklabel_alignment.html :align: center Adjusting pad @@ -436,8 +441,8 @@ ax.axis["left"].label.set_pad(10) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_pad_001.png - :target: ../../gallery/axisartist/simple_axis_pad.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axis_pad_001.png + :target: /gallery/axisartist/simple_axis_pad.html :align: center GridHelper @@ -521,8 +526,8 @@ def inv_tr(x, y): # note that ax2.transData == tr + ax1.transData # Anything you draw in ax2 will match the ticks and grids of ax1. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png - :target: ../../gallery/axisartist/demo_curvelinear_grid.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png + :target: /gallery/axisartist/demo_curvelinear_grid.html :align: center FloatingAxis diff --git a/galleries/tutorials/toolkits/mplot3d.py b/galleries/users_explain/toolkits/mplot3d.py similarity index 60% rename from galleries/tutorials/toolkits/mplot3d.py rename to galleries/users_explain/toolkits/mplot3d.py index f3ff920e036f..c50e18c5bfc6 100644 --- a/galleries/tutorials/toolkits/mplot3d.py +++ b/galleries/users_explain/toolkits/mplot3d.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/toolkits/mplot3d + +.. _mplot3d: + =================== The mplot3d toolkit =================== @@ -20,8 +25,8 @@ Multiple 3D subplots can be added on the same figure, as for 2D subplots. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_subplot3d_001.png - :target: ../../gallery/mplot3d/subplot3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_subplot3d_001.png + :target: /gallery/mplot3d/subplot3d.html :align: center .. versionchanged:: 3.2.0 @@ -38,8 +43,8 @@ ========== See `.Axes3D.plot` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_lines3d_001.png - :target: ../../gallery/mplot3d/lines3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_lines3d_001.png + :target: /gallery/mplot3d/lines3d.html :align: center .. _scatter3d: @@ -48,8 +53,8 @@ ============= See `.Axes3D.scatter` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_scatter3d_001.png - :target: ../../gallery/mplot3d/scatter3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_scatter3d_001.png + :target: /gallery/mplot3d/scatter3d.html :align: center .. _wireframe: @@ -58,8 +63,8 @@ =============== See `.Axes3D.plot_wireframe` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_wire3d_001.png - :target: ../../gallery/mplot3d/wire3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_wire3d_001.png + :target: /gallery/mplot3d/wire3d.html :align: center .. _surface: @@ -68,8 +73,8 @@ ============= See `.Axes3D.plot_surface` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_surface3d_001.png - :target: ../../gallery/mplot3d/surface3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_surface3d_001.png + :target: /gallery/mplot3d/surface3d.html :align: center .. _trisurface: @@ -78,8 +83,8 @@ ================= See `.Axes3D.plot_trisurf` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_trisurf3d_001.png - :target: ../../gallery/mplot3d/trisurf3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_trisurf3d_001.png + :target: /gallery/mplot3d/trisurf3d.html :align: center .. _contour3d: @@ -88,8 +93,8 @@ ============= See `.Axes3D.contour` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_contour3d_001.png - :target: ../../gallery/mplot3d/contour3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_contour3d_001.png + :target: /gallery/mplot3d/contour3d.html :align: center .. _contourf3d: @@ -98,8 +103,8 @@ ==================== See `.Axes3D.contourf` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_contourf3d_001.png - :target: ../../gallery/mplot3d/contourf3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_contourf3d_001.png + :target: /gallery/mplot3d/contourf3d.html :align: center .. versionadded:: 1.1.0 @@ -112,8 +117,8 @@ ============= See `.Axes3D.add_collection3d` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_polys3d_001.png - :target: ../../gallery/mplot3d/polys3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_polys3d_001.png + :target: /gallery/mplot3d/polys3d.html :align: center .. _bar3d: @@ -122,8 +127,8 @@ ========= See `.Axes3D.bar` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_bars3d_001.png - :target: ../../gallery/mplot3d/bars3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_bars3d_001.png + :target: /gallery/mplot3d/bars3d.html :align: center .. _quiver3d: @@ -132,16 +137,16 @@ ====== See `.Axes3D.quiver` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_quiver3d_001.png - :target: ../../gallery/mplot3d/quiver3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_quiver3d_001.png + :target: /gallery/mplot3d/quiver3d.html :align: center .. _2dcollections3d: 2D plots in 3D ============== -.. figure:: ../../gallery/mplot3d/images/sphx_glr_2dcollections3d_001.png - :target: ../../gallery/mplot3d/2dcollections3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_2dcollections3d_001.png + :target: /gallery/mplot3d/2dcollections3d.html :align: center .. _text3d: @@ -150,7 +155,7 @@ ==== See `.Axes3D.text` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_text3d_001.png - :target: ../../gallery/mplot3d/text3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_text3d_001.png + :target: /gallery/mplot3d/text3d.html :align: center """ diff --git a/lib/matplotlib/_constrained_layout.py b/lib/matplotlib/_constrained_layout.py index 9554a156f1ec..fc09a407a36a 100644 --- a/lib/matplotlib/_constrained_layout.py +++ b/lib/matplotlib/_constrained_layout.py @@ -10,7 +10,7 @@ ``figure.subplots()`` or ``figure.add_subplots()`` will participate in the layout. Axes manually placed via ``figure.add_axes()`` will not. -See Tutorial: :doc:`/tutorials/intermediate/constrainedlayout_guide` +See Tutorial: :ref:`constrainedlayout_guide` General idea: ------------- @@ -43,7 +43,7 @@ columns and rows. It's possible that the margins take up the whole figure, in which case the algorithm is not applied and a warning is raised. -See the tutorial doc:`/tutorials/intermediate/constrainedlayout_guide` +See the tutorial :ref:`constrainedlayout_guide` for more discussion of the algorithm with examples. """ diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index 7e2b64b6304a..7101d477c145 100644 --- a/lib/matplotlib/artist.py +++ b/lib/matplotlib/artist.py @@ -857,7 +857,7 @@ def get_in_layout(self): Return boolean flag, ``True`` if artist is included in layout calculations. - E.g. :doc:`/tutorials/intermediate/constrainedlayout_guide`, + E.g. :ref:`constrainedlayout_guide`, `.Figure.tight_layout()`, and ``fig.savefig(fname, bbox_inches='tight')``. """ @@ -1067,7 +1067,7 @@ def set_animated(self, b): using blitting. See also `matplotlib.animation` and - :doc:`/tutorials/advanced/blitting`. + :ref:`blitting`. Parameters ---------- @@ -1080,7 +1080,7 @@ def set_animated(self, b): def set_in_layout(self, in_layout): """ Set if artist is to be included in layout calculations, - E.g. :doc:`/tutorials/intermediate/constrainedlayout_guide`, + E.g. :ref:`constrainedlayout_guide`, `.Figure.tight_layout()`, and ``fig.savefig(fname, bbox_inches='tight')``. diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 7d8e415ec17c..23c57105ca5e 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -303,7 +303,7 @@ def legend(self, *args, **kwargs): Notes ----- Some artists are not supported by this function. See - :doc:`/tutorials/intermediate/legend_guide` for details. + :ref:`legend_guide` for details. Examples -------- @@ -5551,7 +5551,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None, Note that the vertical axis points upward for 'lower' but downward for 'upper'. - See the :doc:`/tutorials/intermediate/imshow_extent` tutorial for + See the :ref:`imshow_extent` tutorial for examples and a more detailed description. extent : floats (left, right, bottom, top), optional @@ -5572,7 +5572,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None, - For ``origin == 'lower'`` the default is ``(-0.5, numcols-0.5, -0.5, numrows-0.5)``. - See the :doc:`/tutorials/intermediate/imshow_extent` tutorial for + See the :ref:`imshow_extent` tutorial for examples and a more detailed description. filternorm : bool, default: True diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py index 55c78e83ab62..38158db9564a 100644 --- a/lib/matplotlib/cm.py +++ b/lib/matplotlib/cm.py @@ -5,14 +5,13 @@ :doc:`/gallery/color/colormap_reference` for a list of builtin colormaps. - :doc:`/tutorials/colors/colormap-manipulation` for examples of how to - make colormaps. + :ref:`colormap-manipulation` for examples of how to make + colormaps. - :doc:`/tutorials/colors/colormaps` an in-depth discussion of - choosing colormaps. + :ref:`colormaps` an in-depth discussion of choosing + colormaps. - :doc:`/tutorials/colors/colormapnorms` for more details about data - normalization. + :ref:`colormapnorms` for more details about data normalization. """ from collections.abc import Mapping @@ -681,7 +680,7 @@ def changed(self): If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :doc:`/tutorials/colors/colormapnorms`). + (see :ref:`colormapnorms`). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a list of available scales, call `matplotlib.scale.get_scale_names()`. In that case, a suitable `.Normalize` subclass is dynamically generated diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index 57be04062de5..304eccca1bd7 100644 --- a/lib/matplotlib/colors.py +++ b/lib/matplotlib/colors.py @@ -16,12 +16,12 @@ .. seealso:: - :doc:`/tutorials/colors/colormap-manipulation` for examples of how to + :ref:`colormap-manipulation` for examples of how to make colormaps and - :doc:`/tutorials/colors/colormaps` for a list of built-in colormaps. + :ref:`colormaps` for a list of built-in colormaps. - :doc:`/tutorials/colors/colormapnorms` for more details about data + :ref:`colormapnorms` for more details about data normalization More colormaps are available at palettable_. @@ -33,7 +33,7 @@ RGBA array (`to_rgba_array`). Caching is used for efficiency. Colors that Matplotlib recognizes are listed at -:doc:`/tutorials/colors/colors`. +:ref:`colors_def`. .. _palettable: https://jiffyclub.github.io/palettable/ .. _xkcd color survey: https://xkcd.com/color/rgb/ @@ -502,7 +502,7 @@ def to_hex(c, keep_alpha=False): Parameters ---------- - c : :doc:`color ` or `numpy.ma.masked` + c : :ref:`color ` or `numpy.ma.masked` keep_alpha : bool, default: False If False, use the ``#rrggbb`` format, otherwise use ``#rrggbbaa``. diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 3db7a102a31b..9d3f630ea1ac 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1108,7 +1108,7 @@ def legend(self, *args, **kwargs): Notes ----- Some artists are not supported by this function. See - :doc:`/tutorials/intermediate/legend_guide` for details. + :ref:`legend_guide` for details. """ handles, labels, extra_args, kwargs = mlegend._parse_legend_args( @@ -1805,7 +1805,7 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, This is a helper function to build complex GridSpec layouts visually. - See :doc:`/gallery/subplots_axes_and_figures/mosaic` + See :ref:`mosaic` for an example and full API documentation Parameters @@ -2266,7 +2266,7 @@ def get_constrained_layout(self): """ Return whether constrained layout is being used. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. """ return self._parent.get_constrained_layout() @@ -2277,7 +2277,7 @@ def get_constrained_layout_pads(self, relative=False): Returns a list of ``w_pad, h_pad`` in inches and ``wspace`` and ``hspace`` as fractions of the subplot. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. Parameters ---------- @@ -2427,7 +2427,7 @@ def __init__(self, to avoid overlapping axes decorations. Can handle complex plot layouts and colorbars, and is thus recommended. - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :ref:`constrainedlayout_guide` for examples. - 'compressed': uses the same algorithm as 'constrained', but @@ -2776,7 +2776,7 @@ def get_constrained_layout(self): """ Return whether constrained layout is being used. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. """ return isinstance(self.get_layout_engine(), ConstrainedLayoutEngine) @@ -2819,7 +2819,7 @@ def set_constrained_layout_pads(self, **kwargs): Tip: The parameters can be passed from a dictionary by using ``fig.set_constrained_layout(**pad_dict)``. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. Parameters ---------- @@ -2853,7 +2853,7 @@ def get_constrained_layout_pads(self, relative=False): ``wspace`` and ``hspace`` as fractions of the subplot. All values are None if ``constrained_layout`` is not used. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. Parameters ---------- diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py index 11dc05b0e9d2..c9d5fbd1c7ed 100644 --- a/lib/matplotlib/gridspec.py +++ b/lib/matplotlib/gridspec.py @@ -7,8 +7,7 @@ Often, users need not access this module directly, and can use higher-level methods like `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` and -`~.Figure.subfigures`. See the tutorial -:doc:`/tutorials/intermediate/arranging_axes` for a guide. +`~.Figure.subfigures`. See the tutorial :ref:`arranging_axes` for a guide. """ import copy diff --git a/lib/matplotlib/layout_engine.py b/lib/matplotlib/layout_engine.py index a3eab93da329..9d4b8e8a681e 100644 --- a/lib/matplotlib/layout_engine.py +++ b/lib/matplotlib/layout_engine.py @@ -127,7 +127,7 @@ def execute(self, fig): class TightLayoutEngine(LayoutEngine): """ Implements the ``tight_layout`` geometry management. See - :doc:`/tutorials/intermediate/tight_layout_guide` for details. + :ref:`tight_layout_guide` for details. """ _adjust_compatible = True _colorbar_gridspec = True @@ -191,7 +191,7 @@ def set(self, *, pad=None, w_pad=None, h_pad=None, rect=None): class ConstrainedLayoutEngine(LayoutEngine): """ Implements the ``constrained_layout`` geometry management. See - :doc:`/tutorials/intermediate/constrainedlayout_guide` for details. + :ref:`constrainedlayout_guide` for details. """ _adjust_compatible = False diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index 11fb0c3ba4a5..95b0e50b3015 100644 --- a/lib/matplotlib/legend.py +++ b/lib/matplotlib/legend.py @@ -6,8 +6,8 @@ It is unlikely that you would ever create a Legend instance manually. Most users would normally create a legend via the `~.Axes.legend` - function. For more details on legends there is also a :doc:`legend guide - `. + function. For more details on legends there is also a :ref:`legend guide + `. The `Legend` class is a container of legend handles and legend texts. @@ -17,7 +17,7 @@ types are covered by the default legend handlers, custom legend handlers can be defined to support arbitrary objects. -See the :doc:`legend guide ` for more +See the :ref`` for more information. """ @@ -314,7 +314,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas): right side of the layout. In addition to the values of *loc* listed above, we have 'outside right upper', 'outside right lower', 'outside left upper', and 'outside left lower'. See - :doc:`/tutorials/intermediate/legend_guide` for more details. + :ref:`legend_guide` for more details. """ _legend_kw_figure_st = ( @@ -863,7 +863,7 @@ def _init_legend_box(self, handles, labels, markerfirst=True): f"{type(orig_handle).__name__} " "instances.\nA proxy artist may be used " "instead.\nSee: https://matplotlib.org/" - "stable/tutorials/intermediate/legend_guide.html" + "stable/users/explain/axes/legend_guide.html" "#controlling-the-legend-entries") # No handle for this artist, so we just defer to None. handle_list.append(None) diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py index 0790150e3a9c..ed902193c5f6 100644 --- a/lib/matplotlib/legend_handler.py +++ b/lib/matplotlib/legend_handler.py @@ -5,8 +5,8 @@ This is a low-level legend API, which most end users do not need. - We recommend that you are familiar with the :doc:`legend guide - ` before reading this documentation. + We recommend that you are familiar with the :ref:`legend guide + ` before reading this documentation. Legend handlers are expected to be a callable object with a following signature:: diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py index 2037a64f8d90..cf4634575f88 100644 --- a/lib/matplotlib/markers.py +++ b/lib/matplotlib/markers.py @@ -70,7 +70,7 @@ for `.Axes.scatter`). Note that special symbols can be defined via the -:doc:`STIX math font `, +:ref:`STIX math font `, e.g. ``"$\u266B$"``. For an overview over the STIX font symbols refer to the `STIX font table `_. Also see the :doc:`/gallery/text_labels_and_annotations/stix_fonts_demo`. diff --git a/lib/matplotlib/mathtext.py b/lib/matplotlib/mathtext.py index 276edf5c764e..e538d451f8dd 100644 --- a/lib/matplotlib/mathtext.py +++ b/lib/matplotlib/mathtext.py @@ -2,7 +2,7 @@ A module for parsing a subset of the TeX math syntax and rendering it to a Matplotlib backend. -For a tutorial of its usage, see :doc:`/tutorials/text/mathtext`. This +For a tutorial of its usage, see :ref:`mathtext`. This document is primarily concerned with implementation details. The module uses pyparsing_ to parse the TeX expression. diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc index bf3aab7949ff..1cddb67de8cb 100644 --- a/lib/matplotlib/mpl-data/matplotlibrc +++ b/lib/matplotlib/mpl-data/matplotlibrc @@ -16,7 +16,7 @@ ## $HOME/.matplotlib/matplotlibrc ## and edit that copy. ## -## See https://matplotlib.org/stable/tutorials/introductory/customizing.html#customizing-with-matplotlibrc-files +## See https://matplotlib.org/stable/users/explain/customizing.html#customizing-with-matplotlibrc-files ## for more details on the paths which are checked for the configuration file. ## ## Blank lines, or lines starting with a comment symbol, are ignored, as are @@ -309,7 +309,7 @@ ## * LaTeX * ## *************************************************************************** ## For more information on LaTeX properties, see -## https://matplotlib.org/stable/tutorials/text/usetex.html +## https://matplotlib.org/stable/users/explain/text/usetex.html #text.usetex: False # use latex for all text handling. The following fonts # are supported through the usual rc parameter settings: # new century schoolbook, bookman, times, palatino, @@ -416,7 +416,7 @@ # As opposed to all other parameters in this file, the color # values must be enclosed in quotes for this parameter, # e.g. '1f77b4', instead of 1f77b4. - # See also https://matplotlib.org/stable/tutorials/intermediate/color_cycle.html + # See also https://matplotlib.org/stable/users/explain/artists/color_cycle.html # for more details on prop_cycle usage. #axes.xmargin: .05 # x margin. See `axes.Axes.margins` #axes.ymargin: .05 # y margin. See `axes.Axes.margins` diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 6d583b0c0d15..15971525dcf1 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -4431,8 +4431,8 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None, *, .. note:: Using `ConnectionPatch` across two `~.axes.Axes` instances - is not directly compatible with :doc:`constrained layout - `. Add the artist + is not directly compatible with :ref:`constrained layout + `. Add the artist directly to the `.Figure` instead of adding it to a specific Axes, or exclude it from the layout using ``con.set_in_layout(False)``. diff --git a/lib/matplotlib/patheffects.py b/lib/matplotlib/patheffects.py index 3325fe03d805..ed19db2ad27b 100644 --- a/lib/matplotlib/patheffects.py +++ b/lib/matplotlib/patheffects.py @@ -3,7 +3,7 @@ `.Line2D` and `.Patch`. .. seealso:: - :doc:`/tutorials/advanced/patheffects_guide` + :ref:`patheffects_guide` """ from matplotlib.backend_bases import RendererBase diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 5a71207a2af7..a2668375c49d 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -750,7 +750,7 @@ def figure(num=None, # autoincrement if None, else integer from 1-N to avoid overlapping axes decorations. Can handle complex plot layouts and colorbars, and is thus recommended. - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :ref:`constrainedlayout_guide` for examples. - 'compressed': uses the same algorithm as 'constrained', but @@ -1514,7 +1514,7 @@ def subplot_mosaic(mosaic, *, sharex=False, sharey=False, This is a helper function to build complex GridSpec layouts visually. - See :doc:`/gallery/subplots_axes_and_figures/mosaic` + See :ref:`mosaic` for an example and full API documentation Parameters diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py index 6b666234fc17..3ae18cbf3f30 100644 --- a/lib/matplotlib/transforms.py +++ b/lib/matplotlib/transforms.py @@ -28,7 +28,7 @@ The backends are not expected to handle non-affine transformations themselves. -See the tutorial :doc:`/tutorials/advanced/transforms_tutorial` for examples +See the tutorial :ref:`transforms_tutorial` for examples of how to use transforms. """ diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index 38c6b1c01009..7aedd67ef38c 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -187,9 +187,9 @@ def __init__(self, ax, label, image=None, The color of the button when the mouse is over it. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. - .. versionadded:: 3.7 + .. versionadded:: 3.7 """ super().__init__(ax) @@ -1030,9 +1030,10 @@ def __init__(self, ax, labels, actives=None, *, useblit=True, same length as *labels*. If not given, all buttons are unchecked. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. .. versionadded:: 3.7 + label_props : dict, optional Dictionary of `.Text` properties to be used for the labels. @@ -1637,9 +1638,10 @@ def __init__(self, ax, labels, active=0, activecolor=None, *, specified here or in *radio_props*. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. .. versionadded:: 3.7 + label_props : dict or list of dict, optional Dictionary of `.Text` properties to be used for the labels. @@ -1958,7 +1960,7 @@ class Cursor(AxesWidget): Whether to draw the vertical line. useblit : bool, default: False Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. Other Parameters ---------------- @@ -2052,7 +2054,7 @@ class MultiCursor(Widget): useblit : bool, default: True Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` + See the tutorial :ref:`blitting` for details. horizOn : bool, default: False @@ -2567,7 +2569,7 @@ def on_select(min: float, max: float) -> Any useblit : bool, default: False If True, use the backend-dependent blitting features for faster - canvas updates. See the tutorial :doc:`/tutorials/advanced/blitting` + canvas updates. See the tutorial :ref:`blitting` for details. props : dict, optional @@ -2984,7 +2986,7 @@ class ToolLineHandles: Additional line properties. See `matplotlib.lines.Line2D`. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. """ @@ -3095,7 +3097,7 @@ class ToolHandles: Additional marker properties. See `matplotlib.lines.Line2D`. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. """ @@ -3172,7 +3174,7 @@ def onselect(eclick: MouseEvent, erelease: MouseEvent) useblit : bool, default: False Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. props : dict, optional @@ -3798,7 +3800,7 @@ def onselect(verts): passed the vertices of the selected path. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. props : dict, optional Properties with which the line is drawn, see `matplotlib.lines.Line2D` @@ -3874,7 +3876,7 @@ class PolygonSelector(_SelectorWidget): useblit : bool, default: False Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. props : dict, optional @@ -4223,7 +4225,7 @@ class Lasso(AxesWidget): passed the vertices of the selected path. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. """ diff --git a/pyproject.toml b/pyproject.toml index 2ddd3cbdda06..80fa56e71454 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -112,19 +112,19 @@ convention = "numpy" "lib/mpl_toolkits/axisartist/__init__.py" = ["F401"] "lib/pylab.py" = ["F401", "F403"] -"galleries/tutorials/advanced/path_tutorial.py" = ["E402"] -"galleries/tutorials/advanced/patheffects_guide.py" = ["E402"] -"galleries/tutorials/advanced/transforms_tutorial.py" = ["E402", "E501"] -"galleries/tutorials/colors/colormaps.py" = ["E501"] -"galleries/tutorials/colors/colors.py" = ["E402"] -"galleries/tutorials/intermediate/artists.py" = ["E402"] -"galleries/tutorials/intermediate/constrainedlayout_guide.py" = ["E402"] -"galleries/tutorials/intermediate/legend_guide.py" = ["E402"] -"galleries/tutorials/intermediate/tight_layout_guide.py" = ["E402"] -"galleries/tutorials/introductory/animation_tutorial.py" = ["E501"] -"galleries/tutorials/introductory/images.py" = ["E501"] -"galleries/tutorials/introductory/pyplot.py" = ["E402", "E501"] -"galleries/tutorials/text/annotations.py" = ["E402", "E501"] -"galleries/tutorials/text/mathtext.py" = ["E501"] -"galleries/tutorials/text/text_intro.py" = ["E402"] -"galleries/tutorials/text/text_props.py" = ["E501"] +"galleries/users_explain/artists/paths.py" = ["E402"] +"galleries/users_explain/artists/patheffects_guide.py" = ["E402"] +"galleries/users_explain/artists/transforms_tutorial.py" = ["E402", "E501"] +"galleries/users_explain/colors/colormaps.py" = ["E501"] +"galleries/users_explain/colors/colors.py" = ["E402"] +"galleries/tutorials/artists.py" = ["E402"] +"galleries/users_explain/axes/constrainedlayout_guide.py" = ["E402"] +"galleries/users_explain/axes/legend_guide.py" = ["E402"] +"galleries/users_explain/axes/tight_layout_guide.py" = ["E402"] +"galleries/users_explain/animations/animation.py" = ["E501"] +"galleries/tutorials/images.py" = ["E501"] +"galleries/tutorials/pyplot.py" = ["E402", "E501"] +"galleries/users_explain/text/annotations.py" = ["E402", "E501"] +"galleries/users_explain/text/mathtext.py" = ["E501"] +"galleries/users_explain/text/text_intro.py" = ["E402"] +"galleries/users_explain/text/text_props.py" = ["E501"]