matplotlib · story645 · Jul 15, 2024
diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -137,9 +137,10 @@ Other documentation is generated from the following external sources:
 
 Instructions and guidelines for contributing documentation are found in:
 
-* :doc:`document`
-* :doc:`style_guide`
-* :doc:`tag_guidelines`
+* :doc:`document_build`
+* :doc:`document_format`
+* :doc:`document_style`
+* :doc:`document_tag`
 
 Documentation is contributed through pull requests, so we recommend that you start
 at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to

diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst
@@ -157,7 +157,7 @@ Check that your change does what you intend.  For code changes:
 
 For documentation changes, build the documentation locally to check that
 it renders how you intended and that any new links work correctly.  See
-:ref:`build_docs`.
+:ref:`document-build`.
 
 This is also a good time to look through the :ref:`pr-author-guidelines` and
 address as many of the relevant points as you can.

diff --git a/doc/devel/document_build.rst b/doc/devel/document_build.rst
@@ -0,0 +1,124 @@
+.. redirect-from:: /devel/document
+
+.. _documenting-matplotlib:
+.. _document-build:
+
+*******************
+Build Documentation
+*******************
+
+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.
+
+General file structure
+======================
+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/`,  ``.rst`` files in :file:`doc/api` are created
+when the documentation is built.  See :ref:`writing-docstrings` below.
+
+Second, our example pages, tutorials, and some of the narrative documentation
+are created by `Sphinx Gallery`_.  Sphinx Gallery converts example Python files
+to ``*.rst`` files with the result of Matplotlib plot calls as embedded images.
+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/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.
+
+Set up the build
+================
+
+The documentation for Matplotlib is generated from reStructuredText (ReST_)
+using the Sphinx_ documentation generation tool.
+
+To build the documentation you will need to
+:ref:`set up Matplotlib for development <installing_for_devs>`. Note in
+particular the :ref:`additional dependencies <doc-dependencies>` required to
+build the documentation.
+
+Build the docs
+==============
+
+The documentation sources are found in the :file:`doc/` directory.
+The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
+directories Sphinx parses, how the docs are built, and how the extensions are
+used. To build the documentation in html format, cd into :file:`doc/` and run:
+
+.. code-block:: sh
+
+   make html
+
+.. note::
+
+   Since the documentation is very large, the first build may take 10-20 minutes,
+   depending on your machine.  Subsequent builds will be faster.
+
+Other useful invocations include
+
+.. code-block:: sh
+
+   # Build the html documentation, but skip generation of the gallery images to
+   # save time.
+   make html-noplot
+
+   # Build the html documentation, but skip specific subdirectories.  If a gallery
+   # directory is skipped, the gallery images are not generated.  The first
+   # time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited
+   # to add or remove subdirectories
+   make html-skip-subdirs
+
+   # Delete built files.  May help if you get errors about missing paths or
+   # broken links.
+   make clean
+
+   # Build pdf docs.
+   make latexpdf
+
+The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build
+the complete docs but exit with exit status 1 if there are warnings.  To unset
+it, use
+
+.. code-block:: sh
+
+   make SPHINXOPTS= html
+
+You can use the ``O`` variable to set additional options:
+
+* ``make O=-j4 html`` runs a parallel build with 4 processes.
+* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
+
+Multiple options can be combined, e.g. ``make O='-j4 -Dplot_formats=png:100'
+html``.
+
+On Windows, set the options as environment variables, e.g.:
+
+.. code-block:: bat
+
+   set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html
+
+Show locally built docs
+=======================
+
+The built docs are available in the folder :file:`build/html`. A shortcut
+for opening them in your default browser is:
+
+.. code-block:: sh
+
+   make show
+
+.. _ReST: https://docutils.sourceforge.io/rst.html
+.. _Sphinx: http://www.sphinx-doc.org
+.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/
diff --git a/doc/devel/document.rst → doc/devel/document_format.rst b/doc/devel/document.rst → doc/devel/document_format.rst
@@ -1,128 +1,11 @@
 .. redirect-from:: /devel/documenting_mpl
 
-.. _documenting-matplotlib:
 
-===================
-Write documentation
-===================
-
-Getting started
-===============
-
-General file structure
-----------------------
-
-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.
-
-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/`,  ``.rst`` files in :file:`doc/api` are created
-when the documentation is built.  See :ref:`writing-docstrings` below.
-
-Second, our example pages, tutorials, and some of the narrative documentation
-are created by `Sphinx Gallery`_.  Sphinx Gallery converts example Python files
-to ``*.rst`` files with the result of Matplotlib plot calls as embedded images.
-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/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.
-
-Set up the build
-----------------
-
-The documentation for Matplotlib is generated from reStructuredText (ReST_)
-using the Sphinx_ documentation generation tool.
-
-To build the documentation you will need to
-:ref:`set up Matplotlib for development <installing_for_devs>`. Note in
-particular the :ref:`additional dependencies <doc-dependencies>` required to
-build the documentation.
-
-.. _build_docs:
-
-Build the docs
---------------
-
-The documentation sources are found in the :file:`doc/` directory.
-The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
-directories Sphinx parses, how the docs are built, and how the extensions are
-used. To build the documentation in html format, cd into :file:`doc/` and run:
-
-.. code-block:: sh
-
-   make html
-
-.. note::
+.. _document-format:
 
-   Since the documentation is very large, the first build may take 10-20 minutes,
-   depending on your machine.  Subsequent builds will be faster.
-
-Other useful invocations include
-
-.. code-block:: sh
-
-   # Build the html documentation, but skip generation of the gallery images to
-   # save time.
-   make html-noplot
-
-   # Build the html documentation, but skip specific subdirectories.  If a gallery
-   # directory is skipped, the gallery images are not generated.  The first
-   # time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited
-   # to add or remove subdirectories
-   make html-skip-subdirs
-
-   # Delete built files.  May help if you get errors about missing paths or
-   # broken links.
-   make clean
-
-   # Build pdf docs.
-   make latexpdf
-
-The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build
-the complete docs but exit with exit status 1 if there are warnings.  To unset
-it, use
-
-.. code-block:: sh
-
-   make SPHINXOPTS= html
-
-You can use the ``O`` variable to set additional options:
-
-* ``make O=-j4 html`` runs a parallel build with 4 processes.
-* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
-
-Multiple options can be combined, e.g. ``make O='-j4 -Dplot_formats=png:100'
-html``.
-
-On Windows, set the options as environment variables, e.g.:
-
-.. code-block:: bat
-
-   set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html
-
-Show locally built docs
------------------------
-
-The built docs are available in the folder :file:`build/html`. A shortcut
-for opening them in your default browser is:
-
-.. code-block:: sh
-
-   make show
+*******************
+Write documentation
+*******************
 
 .. _writing-rest-pages:
 
@@ -1189,11 +1072,12 @@ Documentation page analytics are available at
 https://views.scientific-python.org/matplotlib.org.
 
 
+
 .. _ReST: https://docutils.sourceforge.io/rst.html
 .. _Sphinx: http://www.sphinx-doc.org
+.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/
 .. _documentation: https://www.sphinx-doc.org/en/master/contents.html
 .. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup
-.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/
 .. _references: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html
 .. _`numpydoc docstring guide`: https://numpydoc.readthedocs.io/en/latest/format.html
 .. _`Manually passing files`: https://sphinx-gallery.github.io/stable/configuration.html#manually-passing-files
diff --git a/doc/devel/style_guide.rst → doc/devel/document_style.rst b/doc/devel/style_guide.rst → doc/devel/document_style.rst
@@ -1,7 +1,10 @@
+.. redirect-from:: /devel/style_guide
 
-=========================
-Documentation style guide
-=========================
+.. _document_style:
+
+***********
+Style guide
+***********
 
 This guide contains best practices for the language and formatting of Matplotlib
 documentation.
@@ -410,6 +413,7 @@ This style guide is not a comprehensive standard. For a more thorough
 reference of how to contribute to documentation, see the links below. These
 resources contain common best practices for writing documentation.
 
+
 * `Python Developer's Guide <https://devguide.python.org/documenting/#documenting-python>`_
 * `Google Developer Style Guide <https://developers.google.com/style>`_
 * `IBM Style Guide <https://www.oreilly.com/library/view/the-ibm-style/9780132118989/>`_

diff --git a/doc/devel/tag_guidelines.rst → doc/devel/document_tag.rst b/doc/devel/tag_guidelines.rst → doc/devel/document_tag.rst
@@ -1,3 +1,7 @@
+.. redirect-from:: /devel/tag_guidelines
+
+.. _document-tag-guidelines:
+
 Tagging guidelines
 ==================
 
@@ -50,10 +54,10 @@ title or the scope of the example.
     .. toctree::
         :maxdepth: 2
 
-        tag_glossary
+        document_tag_glossary
 
     +++
-    See :doc:`Tag Glossary <tag_glossary>` for a complete list
+    See :ref:`Tag Glossary <document-tag-glossary>` for a complete list
 
 Proposing new tags
 ------------------

diff --git a/doc/devel/tag_glossary.rst → doc/devel/document_tag_glossary.rst b/doc/devel/tag_glossary.rst → doc/devel/document_tag_glossary.rst
@@ -1,3 +1,7 @@
+.. redirect-from:: /devel/tag_glossary
+
+.. _document-tag-glossary:
+
 Tag Glossary
 ============
 

diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -220,9 +220,10 @@ manage, or release manage, these guidelines describe how our current process wor
       .. toctree::
          :maxdepth: 1
 
-         document
-         style_guide
-         tag_guidelines
+         document_build
+         document_format
+         document_style
+         document_tag
 
    .. grid-item-card::
       :shadow: none