Jul 15, 2024
diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst

 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

 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
 .. 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
 .. 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:

 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
 .. 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.
 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
 .. redirect-from:: /devel/tag_guidelines

 .. _document-tag-guidelines:

 Tagging guidelines
 ==================

    .. 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
 .. redirect-from:: /devel/tag_glossary

 .. _document-tag-glossary:

 Tag Glossary
 ============

diff --git a/doc/devel/index.rst b/doc/devel/index.rst
      .. toctree::
         :maxdepth: 1

         document
         style_guide
         tag_guidelines
         document_build
         document_format
         document_style
         document_tag

   .. grid-item-card::
      :shadow: none
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -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/
Original file line number	Diff line number	Diff line change
		@@ -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:

Expand DownExpand Up		@@ -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
Original file line number	Diff line number	Diff line change
		@@ -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.
Expand DownExpand Up		@@ -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/>`_
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1,7 @@
		.. redirect-from:: /devel/tag_guidelines

		.. _document-tag-guidelines:

		Tagging guidelines
		==================

Expand DownExpand Up		@@ -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
		------------------
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,3 +1,7 @@
		.. redirect-from:: /devel/tag_glossary

		.. _document-tag-glossary:

		Tag Glossary
		============

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down