diff --git a/INSTALL.rst b/INSTALL.rst index b682b076dd87..f340f85767b2 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -2,13 +2,6 @@ Installation ############ -.. toctree:: - :hidden: - - installing_source.rst - ../faq/installing_faq.rst - - ============================== Installing an official release ============================== diff --git a/doc/README.txt b/doc/README.txt index bb8b809cea3b..a6dc1c3e6d97 100644 --- a/doc/README.txt +++ b/doc/README.txt @@ -13,15 +13,20 @@ This is the top level build directory for the Matplotlib documentation. All of the documentation is written using sphinx, a python documentation system built on top of ReST. This directory contains -* users - the user documentation, e.g., plotting tutorials, configuration - tips, etc. +* users - the user documentation, e.g., installation, plotting tutorials, +configuration tips, faq, explaations, etc. * devel - documentation for Matplotlib developers -* faq - frequently asked questions - * api - placeholders to automatically generate the api documentation +* tutorials, plot_types, and gallery - automatically +generated by sphinx-gallery from ``../tutorials``, ``../plot_types``, and +``../examples`` respectively (these are only present if docs have been +built locally). + +* thirdpartypackages - redirect to + * mpl_toolkits - documentation of individual toolkits that ship with Matplotlib diff --git a/doc/_templates/mpl_nav_bar.html b/doc/_templates/mpl_nav_bar.html index 242416ff5044..82b8586de449 100644 --- a/doc/_templates/mpl_nav_bar.html +++ b/doc/_templates/mpl_nav_bar.html @@ -10,15 +10,12 @@ Tutorials
  • - Reference + API Reference
  • - Usage guide + Users guide
  • - Develop -
    • -
  • - Release notes + Contributing
    • diff --git a/doc/api/index.rst b/doc/api/index.rst index ed0e7f310275..1f9048787e69 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -1,5 +1,5 @@ -Reference -========= +API Reference +============= When using the library you will typically create :doc:`Figure ` and :doc:`Axes ` objects and diff --git a/doc/api/prev_api_changes/api_changes_3.1.0.rst b/doc/api/prev_api_changes/api_changes_3.1.0.rst index f3737889841f..b300d0d4c469 100644 --- a/doc/api/prev_api_changes/api_changes_3.1.0.rst +++ b/doc/api/prev_api_changes/api_changes_3.1.0.rst @@ -308,7 +308,7 @@ FreeType or libpng are not in the compiler or linker's default path, set the standard environment variables ``CFLAGS``/``LDFLAGS`` on Linux or OSX, or ``CL``/``LINK`` on Windows, to indicate the relevant paths. -See details in :doc:`/users/installing`. +See details in :doc:`/users/installing/index`. Setting artist properties twice or more in the same call ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/conf.py b/doc/conf.py index 4c592bf8fe01..bd95071ec565 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -212,7 +212,7 @@ def _check_dependencies(): source_encoding = "utf-8" # The master toctree document. -master_doc = 'contents' +master_doc = 'users/index' # General substitutions. try: diff --git a/doc/contents.rst b/doc/contents.rst deleted file mode 100644 index 4f070951d9e7..000000000000 --- a/doc/contents.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _complete_sitemap: - -Contents -======== - -.. only:: html - - :Release: |version| - :Date: |today| - - Download `PDF `_ - - -.. toctree:: - :maxdepth: 2 - - users/installing.rst - users/index.rst - users/backmatter.rst - devel/index.rst - users/release_notes.rst - -.. only:: html - - * :ref:`search` diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index c4f004dff07d..e525995e05a8 100644 --- a/doc/devel/contributing.rst +++ b/doc/devel/contributing.rst @@ -275,7 +275,7 @@ Other ways to contribute It also helps us if you spread the word: reference the project from your blog and articles or link to it from your website! If Matplotlib contributes to a project that leads to a scientific publication, please follow the -:doc:`/citing` guidelines. +:doc:`/users/backmatter/citing` guidelines. .. _coding_guidelines: diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index e85dc97a0b23..2355a251be57 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -10,34 +10,35 @@ Getting started General file structure ---------------------- -All documentation is built from the :file:`doc/`, :file:`tutorials/`, and -:file:`examples/` directories. The :file:`doc/` directory contains -configuration files for Sphinx and reStructuredText (ReST_; ``.rst``) files -that are rendered to documentation pages. +All documentation is built from the :file:`doc/`. The :file:`doc/` +directory contains configuration files for Sphinx and reStructuredText +(ReST_; ``.rst``) files that are rendered to documentation pages. - -The main entry point is :file:`doc/index.rst`, which pulls in the -:file:`index.rst` file for the users guide (:file:`doc/users`), developers -guide (:file:`doc/devel`), api reference (:file:`doc/api`), and FAQs -(:file:`doc/faq`). The documentation suite is built as a single document in -order to make the most effective use of cross referencing. - -Sphinx_ also creates ``.rst`` files that are staged in :file:`doc/api` from +Documentation is created in three ways. First, API documentation +(:file:`doc/api`) is created by Sphinx_ from the docstrings of the classes in the Matplotlib library. Except for -:file:`doc/api/api_changes/`, these ``.rst`` files are created when the -documentation is built. - -Similarly, the contents of :file:`doc/gallery` and :file:`doc/tutorials` are -generated by the `Sphinx Gallery`_ from the sources in :file:`examples/` and -:file:`tutorials/`. These sources consist of python scripts that have ReST_ -documentation built into their comments. +:file:`doc/api/api_changes/`, ``.rst`` files in :file:`doc/api` are created +when the documentation is built. See :ref:`writing-docstrings` below. + +Second, the contents of :file:`doc/plot_types`, :file:`doc/gallery` and +:file:`doc/tutorials` are generated by the `Sphinx Gallery`_ from python +files in :file:`plot_types/`, :file:`examples/` and :file:`tutorials/`. +These sources consist of python scripts that have ReST_ documentation built +into their comments. See :ref:`writing-examples-and-tutorials` below. + +Third, Matplotlib has narrative docs written in ReST_ in subdirectories of +:file:`doc/users/`. If you would like to add new documentation that is suited +to an ``.rst`` file rather than a gallery or tutorial example, choose an +appropriate subdirectory to put it in, and add the file to the table of +contents of :file:`index.rst` of the subdirectory. See +:ref:`writing-rest-pages` below. .. note:: - Don't directly edit the ``.rst`` files in :file:`doc/gallery`, - :file:`doc/tutorials`, and :file:`doc/api` (excepting - :file:`doc/api/api_changes/`). Sphinx_ regenerates files in these - directories when building documentation. + Don't directly edit the ``.rst`` files in :file:`doc/plot_types`, + :file:`doc/gallery`, :file:`doc/tutorials`, and :file:`doc/api` + (excepting :file:`doc/api/api_changes/`). Sphinx_ regenerates + files in these directories when building documentation. Setting up the doc build ------------------------ @@ -181,7 +182,7 @@ Documents can be linked with the ``:doc:`` directive: .. code-block:: rst - See the :doc:`/faq/installing_faq` + See the :doc:`/users/faq/installing_faq` See the tutorial :doc:`/tutorials/introductory/sample_plots` @@ -189,14 +190,14 @@ Documents can be linked with the ``:doc:`` directive: will render as: - See the :doc:`/faq/installing_faq` + See the :doc:`/users/faq/installing_faq` See the tutorial :doc:`/tutorials/introductory/sample_plots` See the example :doc:`/gallery/lines_bars_and_markers/simple_plot` Sections can also be given reference names. For instance from the -:doc:`/faq/installing_faq` link: +:doc:`/users/faq/installing_faq` link: .. code-block:: rst diff --git a/doc/index.rst b/doc/index.rst index 7b88cd7374d6..618418a9a641 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -38,7 +38,7 @@ Installation pip install matplotlib -Further details are available in the :doc:`Installation Guide `. +Further details are available in the :doc:`Installation Guide `. Learning resources @@ -53,7 +53,7 @@ Learning resources - :doc:`Quick-start guide ` - :doc:`Plot types ` - `Introductory tutorials <../tutorials/index.html#introductory>`_ - - :doc:`External learning resources ` + - :doc:`External learning resources ` --- @@ -67,7 +67,7 @@ Learning resources Understand how Matplotlib works ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - The :ref:`users-guide-explain` in the :doc:`Usage guide ` + - The :ref:`users-guide-explain` in the :doc:`Users guide ` - Many of the :ref:`Intermediate ` and :ref:`Advanced ` tutorials have explanatory material @@ -106,7 +106,7 @@ you can help! - or improve the :ref:`documentation and code ` -Site map --------- +Users guide +----------- -The :ref:`complete contents of the docs `. +The `contents of the docs `_. diff --git a/doc/citing.rst b/doc/users/backmatter/citing.rst similarity index 59% rename from doc/citing.rst rename to doc/users/backmatter/citing.rst index bbf4f7ea8f75..b7da1ee8df6f 100644 --- a/doc/citing.rst +++ b/doc/users/backmatter/citing.rst @@ -1,4 +1,4 @@ -:orphan: +.. redirect-from:: /citing Citing Matplotlib ================= @@ -8,12 +8,12 @@ please acknowledge this fact by citing `J. D. Hunter, "Matplotlib: A 2D Graphics Environment", Computing in Science & Engineering, vol. 9, no. 3, pp. 90-95, 2007 `_. -.. literalinclude:: ../CITATION.bib +.. literalinclude:: ../../../CITATION.bib :language: bibtex .. container:: sphx-glr-download - :download:`Download BibTeX bibliography file: CITATION.bib <../CITATION.bib>` + :download:`Download BibTeX bibliography file: CITATION.bib <../../../CITATION.bib>` DOIs ---- @@ -30,124 +30,124 @@ By version v3.4.3 - .. image:: _static/zenodo_cache/5194481.svg + .. image:: ../../_static/zenodo_cache/5194481.svg :target: https://doi.org/10.5281/zenodo.5194481 v3.4.2 - .. image:: _static/zenodo_cache/4743323.svg + .. image:: ../../_static/zenodo_cache/4743323.svg :target: https://doi.org/10.5281/zenodo.4743323 v3.4.1 - .. image:: _static/zenodo_cache/4649959.svg + .. image:: ../../_static/zenodo_cache/4649959.svg :target: https://doi.org/10.5281/zenodo.4649959 v3.4.0 - .. image:: _static/zenodo_cache/4638398.svg + .. image:: ../../_static/zenodo_cache/4638398.svg :target: https://doi.org/10.5281/zenodo.4638398 v3.3.4 - .. image:: _static/zenodo_cache/4475376.svg + .. image:: ../../_static/zenodo_cache/4475376.svg :target: https://doi.org/10.5281/zenodo.4475376 v3.3.3 - .. image:: _static/zenodo_cache/4268928.svg + .. image:: ../../_static/zenodo_cache/4268928.svg :target: https://doi.org/10.5281/zenodo.4268928 v3.3.2 - .. image:: _static/zenodo_cache/4030140.svg + .. image:: ../../_static/zenodo_cache/4030140.svg :target: https://doi.org/10.5281/zenodo.4030140 v3.3.1 - .. image:: _static/zenodo_cache/3984190.svg + .. image:: ../../_static/zenodo_cache/3984190.svg :target: https://doi.org/10.5281/zenodo.3984190 v3.3.0 - .. image:: _static/zenodo_cache/3948793.svg + .. image:: ../../_static/zenodo_cache/3948793.svg :target: https://doi.org/10.5281/zenodo.3948793 v3.2.2 - .. image:: _static/zenodo_cache/3898017.svg + .. image:: ../../_static/zenodo_cache/3898017.svg :target: https://doi.org/10.5281/zenodo.3898017 v3.2.1 - .. image:: _static/zenodo_cache/3714460.svg + .. image:: ../../_static/zenodo_cache/3714460.svg :target: https://doi.org/10.5281/zenodo.3714460 v3.2.0 - .. image:: _static/zenodo_cache/3695547.svg + .. image:: ../../_static/zenodo_cache/3695547.svg :target: https://doi.org/10.5281/zenodo.3695547 v3.1.3 - .. image:: _static/zenodo_cache/3633844.svg + .. image:: ../../_static/zenodo_cache/3633844.svg :target: https://doi.org/10.5281/zenodo.3633844 v3.1.2 - .. image:: _static/zenodo_cache/3563226.svg + .. image:: ../../_static/zenodo_cache/3563226.svg :target: https://doi.org/10.5281/zenodo.3563226 v3.1.1 - .. image:: _static/zenodo_cache/3264781.svg + .. image:: ../../_static/zenodo_cache/3264781.svg :target: https://doi.org/10.5281/zenodo.3264781 v3.1.0 - .. image:: _static/zenodo_cache/2893252.svg + .. image:: ../../_static/zenodo_cache/2893252.svg :target: https://doi.org/10.5281/zenodo.2893252 v3.0.3 - .. image:: _static/zenodo_cache/2577644.svg + .. image:: ../../_static/zenodo_cache/2577644.svg :target: https://doi.org/10.5281/zenodo.2577644 v3.0.2 - .. image:: _static/zenodo_cache/1482099.svg + .. image:: ../../_static/zenodo_cache/1482099.svg :target: https://doi.org/10.5281/zenodo.1482099 v3.0.1 - .. image:: _static/zenodo_cache/1482098.svg + .. image:: ../../_static/zenodo_cache/1482098.svg :target: https://doi.org/10.5281/zenodo.1482098 v2.2.5 - .. image:: _static/zenodo_cache/3633833.svg + .. image:: ../../_static/zenodo_cache/3633833.svg :target: https://doi.org/10.5281/zenodo.3633833 v3.0.0 - .. image:: _static/zenodo_cache/1420605.svg + .. image:: ../../_static/zenodo_cache/1420605.svg :target: https://doi.org/10.5281/zenodo.1420605 v2.2.4 - .. image:: _static/zenodo_cache/2669103.svg + .. image:: ../../_static/zenodo_cache/2669103.svg :target: https://doi.org/10.5281/zenodo.2669103 v2.2.3 - .. image:: _static/zenodo_cache/1343133.svg + .. image:: ../../_static/zenodo_cache/1343133.svg :target: https://doi.org/10.5281/zenodo.1343133 v2.2.2 - .. image:: _static/zenodo_cache/1202077.svg + .. image:: ../../_static/zenodo_cache/1202077.svg :target: https://doi.org/10.5281/zenodo.1202077 v2.2.1 - .. image:: _static/zenodo_cache/1202050.svg + .. image:: ../../_static/zenodo_cache/1202050.svg :target: https://doi.org/10.5281/zenodo.1202050 v2.2.0 - .. image:: _static/zenodo_cache/1189358.svg + .. image:: ../../_static/zenodo_cache/1189358.svg :target: https://doi.org/10.5281/zenodo.1189358 v2.1.2 - .. image:: _static/zenodo_cache/1154287.svg + .. image:: ../../_static/zenodo_cache/1154287.svg :target: https://doi.org/10.5281/zenodo.1154287 v2.1.1 - .. image:: _static/zenodo_cache/1098480.svg + .. image:: ../../_static/zenodo_cache/1098480.svg :target: https://doi.org/10.5281/zenodo.1098480 v2.1.0 - .. image:: _static/zenodo_cache/1004650.svg + .. image:: ../../_static/zenodo_cache/1004650.svg :target: https://doi.org/10.5281/zenodo.1004650 v2.0.2 - .. image:: _static/zenodo_cache/573577.svg + .. image:: ../../_static/zenodo_cache/573577.svg :target: https://doi.org/10.5281/zenodo.573577 v2.0.1 - .. image:: _static/zenodo_cache/570311.svg + .. image:: ../../_static/zenodo_cache/570311.svg :target: https://doi.org/10.5281/zenodo.570311 v2.0.0 - .. image:: _static/zenodo_cache/248351.svg + .. image:: ../../_static/zenodo_cache/248351.svg :target: https://doi.org/10.5281/zenodo.248351 v1.5.3 - .. image:: _static/zenodo_cache/61948.svg + .. image:: ../../_static/zenodo_cache/61948.svg :target: https://doi.org/10.5281/zenodo.61948 v1.5.2 - .. image:: _static/zenodo_cache/56926.svg + .. image:: ../../_static/zenodo_cache/56926.svg :target: https://doi.org/10.5281/zenodo.56926 v1.5.1 - .. image:: _static/zenodo_cache/44579.svg + .. image:: ../../_static/zenodo_cache/44579.svg :target: https://doi.org/10.5281/zenodo.44579 v1.5.0 - .. image:: _static/zenodo_cache/32914.svg + .. image:: ../../_static/zenodo_cache/32914.svg :target: https://doi.org/10.5281/zenodo.32914 v1.4.3 - .. image:: _static/zenodo_cache/15423.svg + .. image:: ../../_static/zenodo_cache/15423.svg :target: https://doi.org/10.5281/zenodo.15423 v1.4.2 - .. image:: _static/zenodo_cache/12400.svg + .. image:: ../../_static/zenodo_cache/12400.svg :target: https://doi.org/10.5281/zenodo.12400 v1.4.1 - .. image:: _static/zenodo_cache/12287.svg + .. image:: ../../_static/zenodo_cache/12287.svg :target: https://doi.org/10.5281/zenodo.12287 v1.4.0 - .. image:: _static/zenodo_cache/11451.svg + .. image:: ../../_static/zenodo_cache/11451.svg :target: https://doi.org/10.5281/zenodo.11451 .. END OF AUTOGENERATED diff --git a/doc/users/credits.rst b/doc/users/backmatter/credits.rst similarity index 99% rename from doc/users/credits.rst rename to doc/users/backmatter/credits.rst index 0c0feed44218..04424fc8f263 100644 --- a/doc/users/credits.rst +++ b/doc/users/backmatter/credits.rst @@ -1,5 +1,7 @@ .. Note: This file is auto-generated using generate_credits.py +.. redirect-from:: /users/credits + .. _credits: ******* @@ -11,7 +13,7 @@ Matplotlib was written by John D. Hunter, with contributions from an ever-increasing number of users and developers. The current lead developer is Thomas A. Caswell, who is assisted by many `active developers `_. -Please also see our instructions on :doc:`/citing`. +Please also see our instructions on :doc:`/users/backmatter/citing`. The following is a list of contributors extracted from the git revision control history of the project: diff --git a/doc/users/history.rst b/doc/users/backmatter/history.rst similarity index 99% rename from doc/users/history.rst rename to doc/users/backmatter/history.rst index 19ba9c551ec2..8725e0773522 100644 --- a/doc/users/history.rst +++ b/doc/users/backmatter/history.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/history + History ======= diff --git a/doc/users/backmatter.rst b/doc/users/backmatter/index.rst similarity index 60% rename from doc/users/backmatter.rst rename to doc/users/backmatter/index.rst index 93e88870215d..132c0905b23c 100644 --- a/doc/users/backmatter.rst +++ b/doc/users/backmatter/index.rst @@ -1,11 +1,12 @@ +.. redirect-from:: /users/backmatter Project information ------------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 2 license.rst - ../citing.rst + citing.rst credits.rst history.rst diff --git a/doc/users/license.rst b/doc/users/backmatter/license.rst similarity index 95% rename from doc/users/license.rst rename to doc/users/backmatter/license.rst index 44822d9d95f1..a55927d9f2c5 100644 --- a/doc/users/license.rst +++ b/doc/users/backmatter/license.rst @@ -1,5 +1,7 @@ .. _license: +.. redirect-from:: /users/license + ******* License ******* @@ -44,5 +46,5 @@ control logs. License agreement ================= -.. literalinclude:: ../../LICENSE/LICENSE +.. literalinclude:: ../../../LICENSE/LICENSE :language: none diff --git a/doc/users/explain.rst b/doc/users/explain.rst deleted file mode 100644 index d9d7a8474dbb..000000000000 --- a/doc/users/explain.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _users-guide-explain: - -Explanations ------------- - -.. toctree:: - :maxdepth: 1 - - interactive.rst - fonts.rst diff --git a/doc/users/backends.rst b/doc/users/explain/backends.rst similarity index 100% rename from doc/users/backends.rst rename to doc/users/explain/backends.rst diff --git a/doc/users/event_handling.rst b/doc/users/explain/event_handling.rst similarity index 99% rename from doc/users/event_handling.rst rename to doc/users/explain/event_handling.rst index 3a368d3b5312..6fb208d4c2ac 100644 --- a/doc/users/event_handling.rst +++ b/doc/users/explain/event_handling.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/event_handling + .. _event-handling-tutorial: ************************** diff --git a/doc/users/fonts.rst b/doc/users/explain/fonts.rst similarity index 99% rename from doc/users/fonts.rst rename to doc/users/explain/fonts.rst index 19cdefa15606..9bf2bbc26a2d 100644 --- a/doc/users/fonts.rst +++ b/doc/users/explain/fonts.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/fonts + Fonts in Matplotlib text engine =============================== diff --git a/doc/users/explain/index.rst b/doc/users/explain/index.rst new file mode 100644 index 000000000000..f18676613dfc --- /dev/null +++ b/doc/users/explain/index.rst @@ -0,0 +1,16 @@ +.. _users-guide-explain: + +.. redirect-from:: /users/explain + +Explanations +------------ + +.. toctree:: + :maxdepth: 2 + + backends.rst + interactive.rst + fonts.rst + event_handling.rst + performance.rst + interactive_guide.rst diff --git a/doc/users/interactive.rst b/doc/users/explain/interactive.rst similarity index 99% rename from doc/users/interactive.rst rename to doc/users/explain/interactive.rst index dd86ea0a1b30..0f27b8e01583 100644 --- a/doc/users/interactive.rst +++ b/doc/users/explain/interactive.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/interactive + .. currentmodule:: matplotlib .. _mpl-shell: diff --git a/doc/users/interactive_guide.rst b/doc/users/explain/interactive_guide.rst similarity index 99% rename from doc/users/interactive_guide.rst rename to doc/users/explain/interactive_guide.rst index 959059d7264f..76f014d7b129 100644 --- a/doc/users/interactive_guide.rst +++ b/doc/users/explain/interactive_guide.rst @@ -1,5 +1,7 @@ .. _interactive_figures_and_eventloops: +.. redirect-from:: /users/interactive_guide + .. currentmodule:: matplotlib diff --git a/doc/users/performance.rst b/doc/users/explain/performance.rst similarity index 100% rename from doc/users/performance.rst rename to doc/users/explain/performance.rst diff --git a/doc/faq/environment_variables_faq.rst b/doc/users/faq/environment_variables_faq.rst similarity index 98% rename from doc/faq/environment_variables_faq.rst rename to doc/users/faq/environment_variables_faq.rst index dc26fa9a53f7..36460ae1b0cd 100644 --- a/doc/faq/environment_variables_faq.rst +++ b/doc/users/faq/environment_variables_faq.rst @@ -1,5 +1,7 @@ .. _environment-variables: +.. redirect-from:: /faq/environment_variables_faq + ********************* Environment variables ********************* diff --git a/doc/faq/howto_faq.rst b/doc/users/faq/howto_faq.rst similarity index 98% rename from doc/faq/howto_faq.rst rename to doc/users/faq/howto_faq.rst index 533e7d2b3141..0076cb335ab4 100644 --- a/doc/faq/howto_faq.rst +++ b/doc/users/faq/howto_faq.rst @@ -1,5 +1,7 @@ .. _howto-faq: +.. redirect-from:: /faq/howto_faq + ****** How-to ****** @@ -148,8 +150,8 @@ behavior by specifying the coordinates of the label. The example below shows the default behavior in the left subplots, and the manual setting in the right subplots. -.. figure:: ../gallery/pyplots/images/sphx_glr_align_ylabels_001.png - :target: ../gallery/pyplots/align_ylabels.html +.. figure:: ../../gallery/pyplots/images/sphx_glr_align_ylabels_001.png + :target: ../../gallery/pyplots/align_ylabels.html :align: center :scale: 50 diff --git a/doc/faq/index.rst b/doc/users/faq/index.rst similarity index 67% rename from doc/faq/index.rst rename to doc/users/faq/index.rst index 24e9112465d3..124b1a7f561a 100644 --- a/doc/faq/index.rst +++ b/doc/users/faq/index.rst @@ -1,8 +1,10 @@ .. _faq-index: -###### -How-to -###### +.. redirect-from:: /faq/index + +########################## +How-to and troubleshooting +########################## .. only:: html diff --git a/doc/faq/installing_faq.rst b/doc/users/faq/installing_faq.rst similarity index 99% rename from doc/faq/installing_faq.rst rename to doc/users/faq/installing_faq.rst index 45e3fd99c2ed..c843da427f96 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/users/faq/installing_faq.rst @@ -1,5 +1,7 @@ .. _installing-faq: +.. redirect-from:: /faq/installing_faq + ************** Installing FAQ ************** diff --git a/doc/faq/troubleshooting_faq.rst b/doc/users/faq/troubleshooting_faq.rst similarity index 99% rename from doc/faq/troubleshooting_faq.rst rename to doc/users/faq/troubleshooting_faq.rst index cf9e3b5cf8b9..aedd108f5430 100644 --- a/doc/faq/troubleshooting_faq.rst +++ b/doc/users/faq/troubleshooting_faq.rst @@ -1,5 +1,7 @@ .. _troubleshooting-faq: +.. redirect-from:: /faq/troubleshooting_faq + *************** Troubleshooting *************** diff --git a/doc/users/getting_started.rst b/doc/users/getting_started/index.rst similarity index 89% rename from doc/users/getting_started.rst rename to doc/users/getting_started/index.rst index 1cb7c97952da..7e8863991a41 100644 --- a/doc/users/getting_started.rst +++ b/doc/users/getting_started/index.rst @@ -1,8 +1,8 @@ Getting started =============== -Installation ------------- +Installation quick-start +------------------------ .. container:: twocol @@ -22,12 +22,13 @@ Installation conda install matplotlib -Further details are available in the :doc:`Installation Guide `. +Further details are available in the :doc:`Installation Guide `. + Draw a first plot ----------------- -Here is a minimal example plot you can try out: +Here is a minimal example plot: .. plot:: :include-source: diff --git a/doc/users/index.rst b/doc/users/index.rst index ac5af88b418a..c062a839a5ef 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -1,20 +1,43 @@ .. _users-guide-index: +.. redirect-from:: /contents + + ########### -Usage guide +Users guide ########### + +General +####### + +.. toctree:: + :maxdepth: 2 + + getting_started/index.rst + installing/index.rst + explain/index.rst + faq/index.rst + resources/index.rst + +Reference +######### + .. toctree:: :maxdepth: 2 + ../api/index.rst + ../devel/index.rst + backmatter/index.rst + release_notes.rst + + +Tutorials and examples +###################### + +.. toctree:: + :maxdepth: 1 + ../plot_types/index.rst ../tutorials/index.rst ../gallery/index.rst - getting_started.rst - backends.rst - performance.rst - explain.rst - ../faq/index.rst - ../api/index.rst - ../resources/index.rst - \ No newline at end of file diff --git a/doc/users/installing.rst b/doc/users/installing.rst deleted file mode 100644 index 545ae4fa153e..000000000000 --- a/doc/users/installing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../INSTALL.rst diff --git a/doc/users/installing/index.rst b/doc/users/installing/index.rst new file mode 100644 index 000000000000..50c625bfcd83 --- /dev/null +++ b/doc/users/installing/index.rst @@ -0,0 +1,10 @@ +.. redirect-from:: /installing + + +.. toctree:: + :hidden: + + installing_source.rst + ../faq/installing_faq.rst + +.. include:: ../../../INSTALL.rst diff --git a/doc/users/installing_source.rst b/doc/users/installing/installing_source.rst similarity index 100% rename from doc/users/installing_source.rst rename to doc/users/installing/installing_source.rst diff --git a/doc/users/dflt_style_changes.rst b/doc/users/prev_whats_new/dflt_style_changes.rst similarity index 99% rename from doc/users/dflt_style_changes.rst rename to doc/users/prev_whats_new/dflt_style_changes.rst index 5de399adb053..b36a1a343116 100644 --- a/doc/users/dflt_style_changes.rst +++ b/doc/users/prev_whats_new/dflt_style_changes.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/dflt_style_changes + ============================== Changes to the default style ============================== diff --git a/doc/users/prev_whats_new/whats_new_2.0.0.rst b/doc/users/prev_whats_new/whats_new_2.0.0.rst index 94da59cd1b88..0f5edb7c0e3f 100644 --- a/doc/users/prev_whats_new/whats_new_2.0.0.rst +++ b/doc/users/prev_whats_new/whats_new_2.0.0.rst @@ -17,7 +17,7 @@ The major changes in v2.0 are related to overhauling the default styles. .. toctree:: :maxdepth: 2 - ../dflt_style_changes + dflt_style_changes Improved color conversion API and RGBA support diff --git a/doc/users/release_notes.rst b/doc/users/release_notes.rst index 4608dbc93977..e7ec7c9856f3 100644 --- a/doc/users/release_notes.rst +++ b/doc/users/release_notes.rst @@ -28,8 +28,11 @@ Version 3.4 prev_whats_new/github_stats_3.4.1.rst prev_whats_new/github_stats_3.4.0.rst +Past versions +============= + Version 3.3 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -43,7 +46,7 @@ Version 3.3 prev_whats_new/github_stats_3.3.0.rst Version 3.2 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -54,7 +57,7 @@ Version 3.2 prev_whats_new/github_stats_3.2.0.rst Version 3.1 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -67,7 +70,7 @@ Version 3.1 prev_whats_new/github_stats_3.1.0.rst Version 3.0 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -80,7 +83,7 @@ Version 3.0 prev_whats_new/github_stats_3.0.0.rst Version 2.2 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -88,7 +91,7 @@ Version 2.2 ../api/prev_api_changes/api_changes_2.2.0.rst Version 2.1 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -98,7 +101,7 @@ Version 2.1 ../api/prev_api_changes/api_changes_2.1.0.rst Version 2.0 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -107,7 +110,7 @@ Version 2.0 ../api/prev_api_changes/api_changes_2.0.0.rst Version 1.5 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -117,7 +120,7 @@ Version 1.5 ../api/prev_api_changes/api_changes_1.5.0.rst Version 1.4 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -125,7 +128,7 @@ Version 1.4 ../api/prev_api_changes/api_changes_1.4.x.rst Version 1.3 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -133,7 +136,7 @@ Version 1.3 ../api/prev_api_changes/api_changes_1.3.x.rst Version 1.2 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -142,7 +145,7 @@ Version 1.2 ../api/prev_api_changes/api_changes_1.2.x.rst Version 1.1 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 @@ -150,14 +153,14 @@ Version 1.1 ../api/prev_api_changes/api_changes_1.1.x.rst Version 1.0 -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 prev_whats_new/whats_new_1.0.rst Version 0.x -=========== +~~~~~~~~~~~ .. toctree:: :maxdepth: 1 diff --git a/doc/resources/index.rst b/doc/users/resources/index.rst similarity index 98% rename from doc/resources/index.rst rename to doc/users/resources/index.rst index d80e4b81fdaa..bd83759766fb 100644 --- a/doc/resources/index.rst +++ b/doc/users/resources/index.rst @@ -1,5 +1,7 @@ .. _resources-index: +.. redirect-from:: /resources/index + ****************** External resources ****************** diff --git a/examples/README.txt b/examples/README.txt index 22e3be4d0794..87098fb881ce 100644 --- a/examples/README.txt +++ b/examples/README.txt @@ -10,5 +10,5 @@ This page contains example plots. Click on any image to see the full image and source code. For longer tutorials, see our `tutorials page <../tutorials/index.html>`_. -You can also find `external resources <../resources/index.html>`_ and -a `FAQ <../faq/index.html>`_ in our `user guide <../contents.html>`_. +You can also find `external resources <../users/resources/index.html>`_ and +a `FAQ <../users/faq/index.html>`_ in our `user guide <../users/index.html>`_. diff --git a/examples/event_handling/README.txt b/examples/event_handling/README.txt index 165cb66cb15a..a4c4b6524658 100644 --- a/examples/event_handling/README.txt +++ b/examples/event_handling/README.txt @@ -3,10 +3,11 @@ Event handling ============== -Matplotlib supports :doc:`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 Matplotlib events -are aware of things like data coordinate space and which axes the event occurs -in so you don't have to mess with low level transformation details to go from -canvas space to data space. Object picking examples are also included. +Matplotlib supports :doc:`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 +Matplotlib events are aware of things like data coordinate space and which +axes the event occurs in so you don't have to mess with low level +transformation details to go from canvas space to data space. Object picking +examples are also included. diff --git a/tools/cache_zenodo_svg.py b/tools/cache_zenodo_svg.py index 0167bcf7fd8b..d62ceac2e69c 100644 --- a/tools/cache_zenodo_svg.py +++ b/tools/cache_zenodo_svg.py @@ -106,7 +106,7 @@ def _get_xdg_cache_dir(): } doc_dir = Path(__file__).parent.parent.absolute() / "doc" target_dir = doc_dir / "_static/zenodo_cache" - citing = doc_dir / "citing.rst" + citing = doc_dir / "users/backmatter/citing.rst" target_dir.mkdir(exist_ok=True, parents=True) header = [] footer = [] @@ -134,7 +134,7 @@ def _get_xdg_cache_dir(): fout.write( f""" {version} - .. image:: _static/zenodo_cache/{doi}.svg + .. image:: ../../_static/zenodo_cache/{doi}.svg :target: https://doi.org/10.5281/zenodo.{doi}""" ) fout.write("\n\n")