You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP12.html">MEP12: Improve Gallery and Examples</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP13.html">MEP13: Use properties for Artists</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP14.html">MEP14: Text handling</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP15.html">MEP15: Fix axis autoscaling when limits are specified for one axis only</a></li>
<spanid="documenting-matplotlib"></span><h1>Write documentation<aclass="headerlink" href="#write-documentation" title="Link to this heading">#</a></h1>
<p>All documentation is built from the <codeclass="file docutils literal notranslate"><spanclass="pre">doc/</span></code> folder, but (as explained in this guide)
some of these files are generated from inline docstrings or sphinx gallery files.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Don't directly edit the <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/plot_types</span></code>,
files in these directories when building documentation.</p>
</div>
<sectionid="overview">
<h2>Overview<aclass="headerlink" href="#overview" title="Link to this heading">#</a></h2>
<p>Documentation is created in three ways. First, API documentation (<codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code>) is
created by <aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a> from the docstrings of the classes in the Matplotlib library. Except
for <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/api_changes/</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code> are created
when the documentation is built. See <aclass="reference internal" href="#writing-docstrings"><spanclass="std std-ref">Write API documentation</span></a>.</p>
<p>Second, our example pages, tutorials, and some of the user guide are created by
<aclass="reference external" href="https://sphinx-gallery.readthedocs.io/en/latest/">Sphinx Gallery</a>. Sphinx Gallery converts Python files in <codeclass="file docutils literal notranslate"><spanclass="pre">galleries</span></code> to
<codeclass="docutils literal notranslate"><spanclass="pre">*.rst</span></code> files that contain the results of Matplotlib plot calls as embedded images.
See <aclass="reference internal" href="#writing-examples-and-tutorials"><spanclass="std std-ref">Write examples and tutorials</span></a>.</p>
<p>Third, Matplotlib has informative documentation written in ReST in subdirectories of
<codeclass="file docutils literal notranslate"><spanclass="pre">doc</span></code>. General and historical information about the project is in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/project</span></code>,
the installation guide is in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/install</span></code>, and release notes are managed in
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/release</span></code>. Maintenance documentation is in <codeclass="file docutils literal notranslate"><spanclass="pre">docdevel</span></code> and the website
always redirects to the latest version of these documents. We also maintain a list of
external resources in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/resources/index.rst</span></code>. To improve these documents
or add resources, see <aclass="reference internal" href="#writing-rest-pages"><spanclass="std std-ref">Write ReST pages</span></a>.</p>
<sectionid="theme">
<h3>Theme<aclass="headerlink" href="#theme" title="Link to this heading">#</a></h3>
<p>Matplotlib has a few subprojects that share the same navbar and style, so these
are centralized as a sphinx theme at
<aclass="reference external" href="https://github.com/matplotlib/mpl-sphinx-theme">mpl_sphinx_theme</a>. Changes to the
style or top bar should be made there to propagate across all subprojects.</p>
</section>
</section>
<sectionid="build-the-docs">
<spanid="build-docs"></span><h2>Build the docs<aclass="headerlink" href="#build-the-docs" title="Link to this heading">#</a></h2>
<p>The documentation for Matplotlib is generated from reStructuredText (<aclass="reference external" href="https://docutils.sourceforge.io/rst.html">ReST</a>)
using the <aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a> documentation generation tool. To build the documentation you will
need to <aclass="reference internal" href="development_setup.html#installing-for-devs"><spanclass="std std-ref">set up Matplotlib for development</span></a>. Note in
particular the <aclass="reference internal" href="../install/dependencies.html#doc-dependencies"><spanclass="std std-ref">additional dependencies</span></a> required to
build the documentation.</p>
<p>The documentation sources are found in the <codeclass="file docutils literal notranslate"><spanclass="pre">doc/</span></code> directory.
The configuration file for Sphinx is <codeclass="file docutils literal notranslate"><spanclass="pre">doc/conf.py</span></code>. 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 <codeclass="file docutils literal notranslate"><spanclass="pre">doc/</span></code> and run:</p>
<td><p>If a gallery directory is skipped, the gallery images are not generated. The first
time this is run, it creates <codeclass="docutils literal notranslate"><spanclass="pre">.mpl_skip_subdirs.yaml</span></code> which can be edited to add
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">SPHINXOPTS</span></code> variable is set to <codeclass="docutils literal notranslate"><spanclass="pre">-W</span><spanclass="pre">--keep-going</span></code> by default to build
the complete docs but exit with exit status 1 if there are warnings. To unset it, set
the variable to a blank space. On Windows, set the options as environment variables.</p>
<divclass="highlight-bat notranslate"><divclass="highlight"><pre><span></span><spanclass="k">set</span><spanclass="nv">SPHINXOPTS</span><spanclass="p">=</span><spanclass="p">&</span> make html
</pre></div>
</div>
</div>
</div>
<p>You can use the <codeclass="docutils literal notranslate"><spanclass="pre">O</span></code> variable to set additional options:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">O=-j4</span></code> runs a parallel build with 4 processes.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">O=-Dplot_formats=png:100</span></code> saves figures in low resolution.</p></li>
<divclass="highlight-bat notranslate"><divclass="highlight"><pre><span></span><spanclass="k">set</span><spanclass="nv">SPHINXOPTS</span><spanclass="p">=</span><spanclass="p">&</span><spanclass="k">set</span><spanclass="nv">O</span><spanclass="p">=</span>-j4 -Dplot_formats=png:100 <spanclass="p">&</span> make html
</pre></div>
</div>
</div>
</div>
</section>
<sectionid="show-locally-built-docs">
<h3>Show locally built docs<aclass="headerlink" href="#show-locally-built-docs" title="Link to this heading">#</a></h3>
<p>The built docs are available in the folder <codeclass="file docutils literal notranslate"><spanclass="pre">build/html</span></code>. A shortcut
<spanid="writing-rest-pages"></span><h2>Write ReST pages<aclass="headerlink" href="#write-rest-pages" title="Link to this heading">#</a></h2>
<p>Most documentation is either in the docstrings of individual
classes and methods, in explicit <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files, or in examples and tutorials.
All of these use the <aclass="reference external" href="https://docutils.sourceforge.io/rst.html">ReST</a> syntax and are processed by <aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a>.</p>
<p>The <aclass="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">Sphinx reStructuredText Primer</a> is
a good introduction into using ReST. More complete information is available in
the <aclass="reference external" href="https://docutils.sourceforge.io/rst.html#reference-documentation">reStructuredText reference documentation</a>.</p>
<p>This section contains additional information and conventions how ReST is used
in the Matplotlib documentation.</p>
<sectionid="formatting-and-style-conventions">
<h3>Formatting and style conventions<aclass="headerlink" href="#formatting-and-style-conventions" title="Link to this heading">#</a></h3>
<p>It is useful to strive for consistency in the Matplotlib documentation. Here
are some formatting and style conventions that are used.</p>
<sectionid="section-formatting">
<h4>Section formatting<aclass="headerlink" href="#section-formatting" title="Link to this heading">#</a></h4>
<codeclass="docutils literal notranslate"><spanclass="pre">Upper</span><spanclass="pre">lower</span></code> for section titles, e.g., <codeclass="docutils literal notranslate"><spanclass="pre">Possible</span><spanclass="pre">hangups</span></code> rather than
and the <aclass="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections">Sphinx reStructuredText documentation</a>
for section markup characters, i.e.:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">#</span></code> with overline, for parts. This is reserved for the main title in
<codeclass="docutils literal notranslate"><spanclass="pre">index.rst</span></code>. All other pages should start with "chapter" or lower.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">*</span></code> with overline, for chapters</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">=</span></code>, for sections</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">-</span></code>, for subsections</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">^</span></code>, for subsubsections</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">"</span></code>, for paragraphs</p></li>
</ul>
<p>This may not yet be applied consistently in existing docs.</p>
</section>
<sectionid="table-formatting">
<h4>Table formatting<aclass="headerlink" href="#table-formatting" title="Link to this heading">#</a></h4>
<p>Given the size of the table and length of each entry, use:</p>
<p>For more information, see <aclass="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tables">rst tables</a>.</p>
</section>
<sectionid="function-arguments">
<h4>Function arguments<aclass="headerlink" href="#function-arguments" title="Link to this heading">#</a></h4>
<p>Function arguments and keywords within docstrings should be referred to using
the <codeclass="docutils literal notranslate"><spanclass="pre">*emphasis*</span></code> role. This will keep Matplotlib's documentation consistent
with Python's documentation:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>Here is a description of <spanclass="ge">*argument*</span>
</pre></div>
</div>
<p>Do not use the <codeclass="docutils literal notranslate"><spanclass="pre">`default</span><spanclass="pre">role`</span></code>:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>Do not describe <spanclass="nv">`argument`</span> like this. As per the next section,
this syntax will (unsuccessfully) attempt to resolve the argument as a
link to a class or method in the library.
</pre></div>
</div>
<p>nor the <codeclass="docutils literal notranslate"><spanclass="pre">``literal``</span></code> role:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>Do not describe <spanclass="s">``argument``</span> like this.
</pre></div>
</div>
</section>
</section>
<sectionid="write-mathematical-expressions">
<h3>Write mathematical expressions<aclass="headerlink" href="#write-mathematical-expressions" title="Link to this heading">#</a></h3>
<p>In most cases, you will likely want to use one of <aclass="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/math.html">Sphinx's builtin Math
extensions</a>.
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
<aclass="reference internal" href="../api/sphinxext_mathmpl_api.html#module-matplotlib.sphinxext.mathmpl" title="matplotlib.sphinxext.mathmpl"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.sphinxext.mathmpl</span></code></a> Sphinx extension (See also the
<spanid="internal-section-refs"></span><h3>Refer to other documents and sections<aclass="headerlink" href="#refer-to-other-documents-and-sections" title="Link to this heading">#</a></h3>
<td><p>link to an anchor associated with a heading</p></td>
</tr>
</tbody>
</table>
</div>
<p>Examples:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>See the <spanclass="na">:doc:</span><spanclass="nv">`/install/index`</span>
See the tutorial <spanclass="na">:ref:</span><spanclass="nv">`quick_start`</span>
See the example <spanclass="na">:doc:</span><spanclass="nv">`/gallery/lines_bars_and_markers/simple_plot`</span>
</pre></div>
</div>
<p>will render as:</p>
<blockquote>
<div><p>See the <aclass="reference internal" href="../install/index.html"><spanclass="doc">Installation</span></a></p>
<p>See the tutorial <aclass="reference internal" href="../users/explain/quick_start.html#quick-start"><spanclass="std std-ref">Quick start guide</span></a></p>
<p>See the example <aclass="reference internal" href="../gallery/lines_bars_and_markers/simple_plot.html"><spanclass="doc">Line plot</span></a></p>
</div></blockquote>
<p>Sections can also be given reference labels. For instance from the
<p>will give the following link: <aclass="reference internal" href="../install/index.html#clean-install"><spanclass="std std-ref">How to completely remove Matplotlib</span></a></p>
<p>To maximize internal consistency in section labeling and references,
use hyphen separated, descriptive labels for section references.
Keep in mind that contents may be reorganized later, so
avoid top level names in references like <codeclass="docutils literal notranslate"><spanclass="pre">user</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">devel</span></code>
or <codeclass="docutils literal notranslate"><spanclass="pre">faq</span></code> unless necessary, because for example the FAQ "what is a
backend?" could later become part of the users guide, so the label:</p>
<p>In addition, since underscores are widely used by Sphinx itself, use
hyphens to separate words.</p>
</section>
<sectionid="refer-to-other-code">
<spanid="referring-to-other-code"></span><h3>Refer to other code<aclass="headerlink" href="#refer-to-other-code" title="Link to this heading">#</a></h3>
<p>To link to other methods, classes, or modules in Matplotlib you can use
<p>generates a link like this: <aclass="reference internal" href="../api/collections_api.html#matplotlib.collections.LineCollection" title="matplotlib.collections.LineCollection"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.collections.LineCollection</span></code></a>.</p>
<p><em>Note:</em> We use the sphinx setting <codeclass="docutils literal notranslate"><spanclass="pre">default_role</span><spanclass="pre">=</span><spanclass="pre">'obj'</span></code> so that you don't
have to use qualifiers like <codeclass="docutils literal notranslate"><spanclass="pre">:class:</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">:func:</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">:meth:</span></code> and the likes.</p>
<p>Often, you don't want to show the full package and module name. As long as the
target is unambiguous you can simply leave them out:</p>
<p>and the link still works: <aclass="reference internal" href="../api/collections_api.html#matplotlib.collections.LineCollection" title="matplotlib.collections.LineCollection"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">LineCollection</span></code></a>. Note that you should typically include
the leading dot. It tells Sphinx to look for the given name in the whole project.
See also the explanation at <aclass="reference external" href="https://www.sphinx-doc.org/en/master/usage/domains/python.html#cross-referencing-python-objects">Sphinx: Cross-referencing Python objects</a>.</p>
<p>If there are multiple code elements with the same name (e.g. <codeclass="docutils literal notranslate"><spanclass="pre">plot()</span></code> is a
method in multiple classes), you'll have to extend the definition:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span><spanclass="nv">`.pyplot.plot`</span> or <spanclass="nv">`.Axes.plot`</span>
</pre></div>
</div>
<p>These will show up as <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pyplot.plot</span></code></a> or <aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.plot.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Axes.plot</span></code></a>. To still show only the
last segment you can add a tilde as prefix:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span><spanclass="nv">`~.pyplot.plot`</span> or <spanclass="nv">`~.Axes.plot`</span>
<spanid="rst-figures-and-includes"></span><h3>Include figures and files<aclass="headerlink" href="#include-figures-and-files" title="Link to this heading">#</a></h3>
<p>Image files can directly included in pages with the <codeclass="docutils literal notranslate"><spanclass="pre">image::</span></code> directive.
<p>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.</p>
</section>
<sectionid="move-documentation">
<h3>Move documentation<aclass="headerlink" href="#move-documentation" title="Link to this heading">#</a></h3>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">/doc/topic/old_info.rst</span></code> to
<codeclass="docutils literal notranslate"><spanclass="pre">/doc/topic/new_info.rst</span></code>. We remove <codeclass="docutils literal notranslate"><spanclass="pre">/doc/topic/old_info.rst</span></code> and
in <codeclass="docutils literal notranslate"><spanclass="pre">/doc/topic/new_info.rst</span></code> we insert a <codeclass="docutils literal notranslate"><spanclass="pre">redirect-from</span></code> 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)</p>
<codeclass="docutils literal notranslate"><spanclass="pre">/build/html/topic/old_info.html</span></code> that has a refresh to <codeclass="docutils literal notranslate"><spanclass="pre">new_info.html</span></code>.
If the two files are in different subdirectories:</p>
<p>will yield an html file <codeclass="docutils literal notranslate"><spanclass="pre">/build/html/old_topic/old_info2.html</span></code> that has a
(relative) refresh to <codeclass="docutils literal notranslate"><spanclass="pre">../topic/new_info.html</span></code>.</p>
<p>Use the full path for this directive, relative to the doc root at
<codeclass="docutils literal notranslate"><spanclass="pre">https://matplotlib.org/stable/</span></code>. So <codeclass="docutils literal notranslate"><spanclass="pre">/old_topic/old_info2</span></code> would be
found by users at <codeclass="docutils literal notranslate"><spanclass="pre">http://matplotlib.org/stable/old_topic/old_info2</span></code>.
For clarity, do not use relative links.</p>
</section>
</section>
<sectionid="write-api-documentation">
<spanid="writing-docstrings"></span><h2>Write API documentation<aclass="headerlink" href="#write-api-documentation" title="Link to this heading">#</a></h2>
<p>The API reference documentation describes the library interfaces, e.g. inputs, outputs,
and expected behavior. Most of the API documentation is written in docstrings. These are
comment blocks in source code that explain how the code works. All docstrings should
conform to the <aclass="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc docstring guide</a>. Much of the <aclass="reference external" href="https://docutils.sourceforge.io/rst.html">ReST</a> syntax discussed above
(<aclass="reference internal" href="#writing-rest-pages"><spanclass="std std-ref">Write ReST pages</span></a>) can be used for links and references.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Some parts of the documentation do not yet conform to the current
documentation style. If in doubt, follow the rules given here and not what
you may see in the source code. Pull requests updating docstrings to
the current style are very welcome.</p>
</div>
<p>The pages in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code> are purely technical definitions of
layout; therefore new API reference documentation should be added to the module
docstrings. This placement keeps all API reference documentation about a module in the
same file. These module docstrings eventually populate the <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code> directory
and form the reference documentation for the library.</p>
<sectionid="example-docstring">
<h3>Example docstring<aclass="headerlink" href="#example-docstring" title="Link to this heading">#</a></h3>
<spanclass="sd"> axhline : horizontal line across the Axes</span>
<spanclass="sd"> """</span>
</pre></div>
</div>
<p>See the <aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.hlines.html#matplotlib.axes.Axes.hlines" title="matplotlib.axes.Axes.hlines"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">hlines</span></code></a> documentation for how this renders.</p>
<p>The <aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a> website also contains plenty of <aclass="reference external" href="https://www.sphinx-doc.org/en/master/contents.html">documentation</a> concerning ReST
markup and working with Sphinx in general.</p>
</section>
<sectionid="formatting-conventions">
<h3>Formatting conventions<aclass="headerlink" href="#formatting-conventions" title="Link to this heading">#</a></h3>
<p>The basic docstring conventions are covered in the <aclass="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc docstring guide</a>
and the <aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a> documentation. Some Matplotlib-specific formatting conventions
to keep in mind:</p>
<sectionid="quote-positions">
<h4>Quote positions<aclass="headerlink" href="#quote-positions" title="Link to this heading">#</a></h4>
<p>The quotes for single line docstrings are on the same line (pydocstyle D200):</p>