From 7ed25d12debf0c84e7590e8578f71c90560d417b Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 1 Oct 2021 16:10:46 +0200 Subject: [PATCH 1/8] DOC: more site re-org The root of the index is users/index Most material is now under users/ --- doc/_templates/mpl_nav_bar.html | 9 ++---- doc/api/index.rst | 4 +-- doc/conf.py | 2 +- doc/contents.rst | 25 --------------- doc/index.rst | 10 +++--- doc/users/backmatter.rst | 2 +- doc/{ => users}/citing.rst | 3 +- .../faq/environment_variables_faq.rst | 2 ++ doc/{ => users}/faq/howto_faq.rst | 2 ++ doc/{ => users}/faq/index.rst | 8 +++-- doc/{ => users}/faq/installing_faq.rst | 2 ++ doc/{ => users}/faq/troubleshooting_faq.rst | 2 ++ doc/users/index.rst | 14 ++++++--- doc/users/release_notes.rst | 31 ++++++++++--------- doc/{ => users}/resources/index.rst | 2 ++ examples/README.txt | 4 +-- 16 files changed, 58 insertions(+), 64 deletions(-) delete mode 100644 doc/contents.rst rename doc/{ => users}/citing.rst (99%) rename doc/{ => users}/faq/environment_variables_faq.rst (98%) rename doc/{ => users}/faq/howto_faq.rst (99%) rename doc/{ => users}/faq/index.rst (67%) rename doc/{ => users}/faq/installing_faq.rst (99%) rename doc/{ => users}/faq/troubleshooting_faq.rst (99%) rename doc/{ => users}/resources/index.rst (98%) 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/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/index.rst b/doc/index.rst index 7b88cd7374d6..936eecba3bff 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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/users/backmatter.rst b/doc/users/backmatter.rst index 93e88870215d..321692cff694 100644 --- a/doc/users/backmatter.rst +++ b/doc/users/backmatter.rst @@ -6,6 +6,6 @@ Project information :maxdepth: 1 license.rst - ../citing.rst + citing.rst credits.rst history.rst diff --git a/doc/citing.rst b/doc/users/citing.rst similarity index 99% rename from doc/citing.rst rename to doc/users/citing.rst index bbf4f7ea8f75..db45f7231fb1 100644 --- a/doc/citing.rst +++ b/doc/users/citing.rst @@ -1,4 +1,5 @@ -:orphan: +.. redirect-from:: /citing + Citing Matplotlib ================= 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 99% rename from doc/faq/howto_faq.rst rename to doc/users/faq/howto_faq.rst index 533e7d2b3141..efb7df9b9d8d 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 ****** 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/index.rst b/doc/users/index.rst index ac5af88b418a..f2648a7873f7 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -1,12 +1,16 @@ .. _users-guide-index: +.. redirect-from:: /contents + + ########### -Usage guide +Users guide ########### .. toctree:: :maxdepth: 2 + installing.rst ../plot_types/index.rst ../tutorials/index.rst ../gallery/index.rst @@ -14,7 +18,9 @@ Usage guide backends.rst performance.rst explain.rst - ../faq/index.rst + faq/index.rst ../api/index.rst - ../resources/index.rst - \ No newline at end of file + resources/index.rst + ../devel/index.rst + backmatter.rst + release_notes.rst 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>`_. From 693269adc2d6ae0c9a3a946e6abc31421e12114a Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 1 Oct 2021 18:24:48 +0200 Subject: [PATCH 2/8] DOC: more subdirectories --- INSTALL.rst | 7 -- .../prev_api_changes/api_changes_3.1.0.rst | 2 +- doc/devel/contributing.rst | 2 +- doc/devel/documenting_mpl.rst | 4 +- doc/index.rst | 2 +- doc/users/{ => backmatter}/citing.rst | 85 +++++++++---------- doc/users/{ => backmatter}/credits.rst | 4 +- doc/users/{ => backmatter}/history.rst | 2 + .../{backmatter.rst => backmatter/index.rst} | 1 + doc/users/{ => backmatter}/license.rst | 4 +- doc/users/{ => explain}/event_handling.rst | 2 + doc/users/{ => explain}/fonts.rst | 2 + doc/users/{explain.rst => explain/index.rst} | 2 + doc/users/{ => explain}/interactive.rst | 2 + doc/users/{ => explain}/interactive_guide.rst | 2 + doc/users/faq/howto_faq.rst | 4 +- doc/users/index.rst | 8 +- doc/users/installing.rst | 1 - doc/users/installing/index.rst | 10 +++ .../{ => installing}/installing_source.rst | 0 .../dflt_style_changes.rst | 2 + doc/users/prev_whats_new/whats_new_2.0.0.rst | 2 +- examples/event_handling/README.txt | 15 ++-- tools/cache_zenodo_svg.py | 4 +- 24 files changed, 97 insertions(+), 72 deletions(-) rename doc/users/{ => backmatter}/citing.rst (60%) rename doc/users/{ => backmatter}/credits.rst (99%) rename doc/users/{ => backmatter}/history.rst (99%) rename doc/users/{backmatter.rst => backmatter/index.rst} (78%) rename doc/users/{ => backmatter}/license.rst (95%) rename doc/users/{ => explain}/event_handling.rst (99%) rename doc/users/{ => explain}/fonts.rst (99%) rename doc/users/{explain.rst => explain/index.rst} (77%) rename doc/users/{ => explain}/interactive.rst (99%) rename doc/users/{ => explain}/interactive_guide.rst (99%) delete mode 100644 doc/users/installing.rst create mode 100644 doc/users/installing/index.rst rename doc/users/{ => installing}/installing_source.rst (100%) rename doc/users/{ => prev_whats_new}/dflt_style_changes.rst (99%) 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/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/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..9d0b4cd9eb33 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -189,14 +189,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 936eecba3bff..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 diff --git a/doc/users/citing.rst b/doc/users/backmatter/citing.rst similarity index 60% rename from doc/users/citing.rst rename to doc/users/backmatter/citing.rst index db45f7231fb1..b7da1ee8df6f 100644 --- a/doc/users/citing.rst +++ b/doc/users/backmatter/citing.rst @@ -1,6 +1,5 @@ .. redirect-from:: /citing - Citing Matplotlib ================= @@ -9,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 ---- @@ -31,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 78% rename from doc/users/backmatter.rst rename to doc/users/backmatter/index.rst index 321692cff694..2427eaf07185 100644 --- a/doc/users/backmatter.rst +++ b/doc/users/backmatter/index.rst @@ -1,3 +1,4 @@ +.. redirect-from:: /users/backmatter Project information ------------------- 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/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.rst b/doc/users/explain/index.rst similarity index 77% rename from doc/users/explain.rst rename to doc/users/explain/index.rst index d9d7a8474dbb..9ddf623be642 100644 --- a/doc/users/explain.rst +++ b/doc/users/explain/index.rst @@ -1,5 +1,7 @@ .. _users-guide-explain: +.. redirect-from:: /users/explain + Explanations ------------ 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/faq/howto_faq.rst b/doc/users/faq/howto_faq.rst index efb7df9b9d8d..0076cb335ab4 100644 --- a/doc/users/faq/howto_faq.rst +++ b/doc/users/faq/howto_faq.rst @@ -150,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/users/index.rst b/doc/users/index.rst index f2648a7873f7..46d2d3c074e8 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -10,17 +10,21 @@ Users guide .. toctree:: :maxdepth: 2 - installing.rst + installing/index.rst ../plot_types/index.rst ../tutorials/index.rst ../gallery/index.rst +<<<<<<< HEAD getting_started.rst backends.rst performance.rst explain.rst +======= + explain/index.rst +>>>>>>> 1002a12ba9 (DOC: more subdirectories) faq/index.rst ../api/index.rst resources/index.rst ../devel/index.rst - backmatter.rst + backmatter/index.rst release_notes.rst 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/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") From 88db799442e6052ff3cd6be10fda537e797815df Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sat, 2 Oct 2021 16:01:45 +0200 Subject: [PATCH 3/8] DOC: update documenting_mpl.rst --- doc/README.txt | 13 +++++++--- doc/devel/documenting_mpl.rst | 49 ++++++++++++++++++----------------- 2 files changed, 34 insertions(+), 28 deletions(-) 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/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 9d0b4cd9eb33..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` From b9290518812fe9bd6a62f9f21ae118d397ead9fb Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Mon, 11 Oct 2021 08:48:21 +0200 Subject: [PATCH 4/8] MNT: rebase new getting started page --- doc/users/{getting_started.rst => getting_started/index.rst} | 3 ++- doc/users/index.rst | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) rename doc/users/{getting_started.rst => getting_started/index.rst} (97%) diff --git a/doc/users/getting_started.rst b/doc/users/getting_started/index.rst similarity index 97% rename from doc/users/getting_started.rst rename to doc/users/getting_started/index.rst index 1cb7c97952da..70a4b8c25735 100644 --- a/doc/users/getting_started.rst +++ b/doc/users/getting_started/index.rst @@ -22,7 +22,8 @@ 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 ----------------- diff --git a/doc/users/index.rst b/doc/users/index.rst index 46d2d3c074e8..504dc6391d83 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -10,6 +10,7 @@ Users guide .. toctree:: :maxdepth: 2 + getting_started/index.rst installing/index.rst ../plot_types/index.rst ../tutorials/index.rst From 9049144ad077cd182c740320cd1f04e2dd45dff4 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Mon, 11 Oct 2021 08:49:17 +0200 Subject: [PATCH 5/8] MNT: rebase new getting started page [skip appveyor] [skip actions] [skip azp] --- doc/users/getting_started/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/users/getting_started/index.rst b/doc/users/getting_started/index.rst index 70a4b8c25735..531fd90401c7 100644 --- a/doc/users/getting_started/index.rst +++ b/doc/users/getting_started/index.rst @@ -28,7 +28,7 @@ Further details are available in the :doc:`Installation Guide Date: Mon, 11 Oct 2021 11:42:43 +0200 Subject: [PATCH 6/8] MNT: Map just one level deep [skip appveyor] [skip actions] [skip azp] --- doc/users/getting_started/index.rst | 4 ++-- doc/users/index.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/users/getting_started/index.rst b/doc/users/getting_started/index.rst index 531fd90401c7..7e8863991a41 100644 --- a/doc/users/getting_started/index.rst +++ b/doc/users/getting_started/index.rst @@ -1,8 +1,8 @@ Getting started =============== -Installation ------------- +Installation quick-start +------------------------ .. container:: twocol diff --git a/doc/users/index.rst b/doc/users/index.rst index 504dc6391d83..f8dcfbfbbf72 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -8,7 +8,7 @@ Users guide ########### .. toctree:: - :maxdepth: 2 + :maxdepth: 1 getting_started/index.rst installing/index.rst From ccdffe7aa650b89d88d4b75b2c17c50189f8754e Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 21 Oct 2021 09:36:38 +0200 Subject: [PATCH 7/8] DOC: fix re-org after rebase --- doc/users/backmatter/index.rst | 2 +- doc/users/{ => explain}/backends.rst | 0 doc/users/explain/index.rst | 6 +++++- doc/users/{ => explain}/performance.rst | 0 doc/users/index.rst | 11 ++--------- 5 files changed, 8 insertions(+), 11 deletions(-) rename doc/users/{ => explain}/backends.rst (100%) rename doc/users/{ => explain}/performance.rst (100%) diff --git a/doc/users/backmatter/index.rst b/doc/users/backmatter/index.rst index 2427eaf07185..132c0905b23c 100644 --- a/doc/users/backmatter/index.rst +++ b/doc/users/backmatter/index.rst @@ -4,7 +4,7 @@ Project information ------------------- .. toctree:: - :maxdepth: 1 + :maxdepth: 2 license.rst citing.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/explain/index.rst b/doc/users/explain/index.rst index 9ddf623be642..f18676613dfc 100644 --- a/doc/users/explain/index.rst +++ b/doc/users/explain/index.rst @@ -6,7 +6,11 @@ Explanations ------------ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + backends.rst interactive.rst fonts.rst + event_handling.rst + performance.rst + interactive_guide.rst 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/users/index.rst b/doc/users/index.rst index f8dcfbfbbf72..86aa2de0efcc 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -8,21 +8,14 @@ Users guide ########### .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - getting_started/index.rst installing/index.rst ../plot_types/index.rst ../tutorials/index.rst ../gallery/index.rst -<<<<<<< HEAD - getting_started.rst - backends.rst - performance.rst - explain.rst -======= + getting_started/index.rst explain/index.rst ->>>>>>> 1002a12ba9 (DOC: more subdirectories) faq/index.rst ../api/index.rst resources/index.rst From 3b581082d271354e48a320815e79cac7832ce201 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 21 Oct 2021 11:42:53 +0200 Subject: [PATCH 8/8] DOC: organize TOC --- doc/users/index.rst | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/doc/users/index.rst b/doc/users/index.rst index 86aa2de0efcc..c062a839a5ef 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -7,18 +7,37 @@ Users guide ########### + +General +####### + .. toctree:: :maxdepth: 2 - installing/index.rst - ../plot_types/index.rst - ../tutorials/index.rst - ../gallery/index.rst getting_started/index.rst + installing/index.rst explain/index.rst faq/index.rst - ../api/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