Skip to content

DOC: update and slightly reorg docs docs #31010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
timhoffm merged 1 commit into from
Jan 23, 2026
+83 −93
Merged

DOC: update and slightly reorg docs docs #31010

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 83 additions & 93 deletions doc/devel/document.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,56 +6,53 @@
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.
All documentation is built from the :file:`doc/` folder, but (as explained in this guide)
some of these files are generated from inline docstrings or sphinx gallery files.

.. 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
:file:`doc/gallery`, :file:`doc/tutorials`, :file:`doc/users/explain` and
:file:`doc/api` (except :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.
Overview
========
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`.

Second, our example pages, tutorials, and some of the user guide are created by
`Sphinx Gallery`_. Sphinx Gallery converts Python files in :file:`galleries` to
``*.rst`` files that contain the results of Matplotlib plot calls as embedded images.
See :ref:`writing-examples-and-tutorials`.

Third, Matplotlib has informative documentation written in ReST in subdirectories of
:file:`doc`. General and historical information about the project is in :file:`doc/project`,
the installation guide is in :file:`doc/install`, and release notes are managed in
:file:`doc/release`. Maintenance documentation is in :file:`doc\devel` and the website
always redirects to the latest version of these documents. We also maintain a list of
external resources in :file:`doc/users/resources/index.rst`. To improve these documents
or add resources, see :ref:`writing-rest-pages`.

Theme
-----

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.
Matplotlib has a few subprojects that share the same navbar and style, so these
are centralized as a sphinx theme at
`mpl_sphinx_theme <https://github.com/matplotlib/mpl-sphinx-theme>`_. Changes to the
style or top bar should be made there to propagate across all subprojects.

.. _build_docs:

Build the docs
--------------
==============
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.

The documentation sources are found in the :file:`doc/` directory.
The configuration file for Sphinx is :file:`doc/conf.py`. It controls which
Expand All @@ -71,6 +68,9 @@ used. To build the documentation in html format, cd into :file:`doc/` and run:
Since the documentation is very large, the first build may take 10-20 minutes,
depending on your machine. Subsequent builds will be faster.

Build options
-------------

Other useful invocations include

.. code-block:: sh
Expand Down Expand Up @@ -124,6 +124,7 @@ for opening them in your default browser is:

make show


.. _writing-rest-pages:

Write ReST pages
Expand Down Expand Up @@ -215,6 +216,18 @@ nor the ````literal```` role:
Do not describe ``argument`` like this.


Write mathematical expressions
------------------------------

In most cases, you will likely want to use one of `Sphinx's builtin Math
extensions <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`__.
In rare cases we want the rendering of the mathematical text in the
documentation html to exactly match with the rendering of the mathematical
expression in the Matplotlib figure. In these cases, you can use the
`matplotlib.sphinxext.mathmpl` Sphinx extension (See also the
:doc:`../users/explain/text/mathtext` tutorial.)


.. _internal-section-refs:

Refer to other documents and sections
Expand Down Expand Up @@ -386,16 +399,38 @@ Note that the python script that generates the plot is referred to, rather than
any plot that is created. Sphinx-gallery will provide the correct reference
when the documentation is built.

Tools for writing mathematical expressions
------------------------------------------
Move documentation
------------------
Sometimes it is desirable to move or consolidate documentation. With no
action this will lead to links either going dead (404) or pointing to old
versions of the documentation. Instead, replace the old page
with an html refresh that immediately redirects the viewer to the new
page. So, for example we move ``/doc/topic/old_info.rst`` to
``/doc/topic/new_info.rst``. We remove ``/doc/topic/old_info.rst`` and
in ``/doc/topic/new_info.rst`` we insert a ``redirect-from`` directive that
tells sphinx to still make the old file with the html refresh/redirect in it
(probably near the top of the file to make it noticeable)

.. code-block:: rst

.. redirect-from:: /topic/old_info

In the built docs this will yield an html file
``/build/html/topic/old_info.html`` that has a refresh to ``new_info.html``.
If the two files are in different subdirectories:

.. code-block:: rst

.. redirect-from:: /old_topic/old_info2

will yield an html file ``/build/html/old_topic/old_info2.html`` that has a
(relative) refresh to ``../topic/new_info.html``.

Use the full path for this directive, relative to the doc root at
``https://matplotlib.org/stable/``. So ``/old_topic/old_info2`` would be
found by users at ``http://matplotlib.org/stable/old_topic/old_info2``.
For clarity, do not use relative links.

In most cases, you will likely want to use one of `Sphinx's builtin Math
extensions <https://www.sphinx-doc.org/en/master/usage/extensions/math.html>`__.
In rare cases we want the rendering of the mathematical text in the
documentation html to exactly match with the rendering of the mathematical
expression in the Matplotlib figure. In these cases, you can use the
`matplotlib.sphinxext.mathmpl` Sphinx extension (See also the
:doc:`../users/explain/text/mathtext` tutorial.)

.. _writing-docstrings:

Expand Down Expand Up @@ -1164,51 +1199,6 @@ Format
:code: The code should be about 5-10 lines with minimal customization. Plots in
this gallery use the ``_mpl-gallery`` stylesheet for a uniform aesthetic.

Miscellaneous
=============

Move documentation
------------------

Sometimes it is desirable to move or consolidate documentation. With no
action this will lead to links either going dead (404) or pointing to old
versions of the documentation. Preferable is to replace the old page
with an html refresh that immediately redirects the viewer to the new
page. So, for example we move ``/doc/topic/old_info.rst`` to
``/doc/topic/new_info.rst``. We remove ``/doc/topic/old_info.rst`` and
in ``/doc/topic/new_info.rst`` we insert a ``redirect-from`` directive that
tells sphinx to still make the old file with the html refresh/redirect in it
(probably near the top of the file to make it noticeable)

.. code-block:: rst

.. redirect-from:: /topic/old_info

In the built docs this will yield an html file
``/build/html/topic/old_info.html`` that has a refresh to ``new_info.html``.
If the two files are in different subdirectories:

.. code-block:: rst

.. redirect-from:: /old_topic/old_info2

will yield an html file ``/build/html/old_topic/old_info2.html`` that has a
(relative) refresh to ``../topic/new_info.html``.

Use the full path for this directive, relative to the doc root at
``https://matplotlib.org/stable/``. So ``/old_topic/old_info2`` would be
found by users at ``http://matplotlib.org/stable/old_topic/old_info2``.
For clarity, do not use relative links.

Navbar and style
----------------

Matplotlib has a few subprojects that share the same navbar and style, so these
are centralized as a sphinx theme at
`mpl_sphinx_theme <https://github.com/matplotlib/mpl-sphinx-theme>`_. Changes to the
style or topbar should be made there to propagate across all subprojects.


Analytics
==========

Expand Down
Loading