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
<divid="unreleased-message"> You are reading an old version of the documentation (v3.3.4). For the latest version see <ahref="https://matplotlib.org/stable/devel/documenting_mpl.html">https://matplotlib.org/stable/devel/documenting_mpl.html</a></div>
<spanid="documenting-matplotlib"></span><h1>Writing documentation<aclass="headerlink" href="#writing-documentation" title="Permalink to this headline">¶</a></h1>
<divclass="contents multicol-toc local topic" id="contents">
<h2><aclass="toc-backref" href="#contents">Getting started</a><aclass="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="general-file-structure">
<h3><aclass="toc-backref" href="#contents">General file structure</a><aclass="headerlink" href="#general-file-structure" title="Permalink to this headline">¶</a></h3>
<p>All documentation is built from the <codeclass="file docutils literal notranslate"><spanclass="pre">doc/</span></code>, <codeclass="file docutils literal notranslate"><spanclass="pre">tutorials/</span></code>, and
configuration files for Sphinx and reStructuredText (<aclass="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a>; <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code>) files
that are rendered to documentation pages.</p>
<p>The main entry point is <codeclass="file docutils literal notranslate"><spanclass="pre">doc/index.rst</span></code>, which pulls in the
<codeclass="file docutils literal notranslate"><spanclass="pre">index.rst</span></code> file for the users guide (<codeclass="file docutils literal notranslate"><spanclass="pre">doc/users</span></code>), developers
guide (<codeclass="file docutils literal notranslate"><spanclass="pre">doc/devel</span></code>), api reference (<codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code>), and FAQs
(<codeclass="file docutils literal notranslate"><spanclass="pre">doc/faq</span></code>). The documentation suite is built as a single document in
order to make the most effective use of cross referencing.</p>
<p><aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a> also creates <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files that are staged in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code> 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>, these <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files are created when the
documentation is built.</p>
<p>Similarly, the contents of <codeclass="file docutils literal notranslate"><spanclass="pre">doc/gallery</span></code> and <codeclass="file docutils literal notranslate"><spanclass="pre">doc/tutorials</span></code> are
generated by the <aclass="reference external" href="https://sphinx-gallery.readthedocs.io/en/latest/">Sphinx Gallery</a> from the sources in <codeclass="file docutils literal notranslate"><spanclass="pre">examples/</span></code> and
<codeclass="file docutils literal notranslate"><spanclass="pre">tutorials/</span></code>. These sources consist of python scripts that have <aclass="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a>
documentation built into their comments.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">Don't directly edit the <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/gallery</span></code>,
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/tutorials</span></code>, and <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code> (excepting
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/api/api_changes/</span></code>). <aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a> regenerates files in these
directories when building documentation.</p>
</div>
</div>
<divclass="section" id="installing-dependencies">
<h3><aclass="toc-backref" href="#contents">Installing dependencies</a><aclass="headerlink" href="#installing-dependencies" title="Permalink to this headline">¶</a></h3>
<p>The documentation for Matplotlib is generated from reStructuredText (<aclass="reference external" href="http://docutils.sourceforge.net/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 (1) set up an appropriate Python environment and (2)
separately install LaTeX and Graphviz.</p>
<p>To (1) set up an appropriate Python environment for building the
documentation, you should:</p>
<ulclass="simple">
<li>create a clean virtual environment with no existing Matplotlib
installation</li>
<li>install the Python packages required for Matplotlib</li>
<li>install the additional Python packages required to build the documentation</li>
</ul>
<p>There are several extra python packages that are needed to build the
documentation. They are listed in <codeclass="file docutils literal notranslate"><spanclass="pre">doc-requirements.txt</span></code>, which is
shown below:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Requirements for building docs</span>
<spanclass="c1">#</span>
<spanclass="c1"># You will first need a matching Matplotlib installation</span>
<spanclass="c1"># e.g (from the Matplotlib root directory)</span>
<spanclass="c1"># pip install -e .</span>
<spanclass="c1">#</span>
<spanclass="c1"># Install the documentation requirements with:</span>
<pclass="last">The documentation will not build without LaTeX and Graphviz. These are not
Python packages and must be installed separately.</p>
</div>
</div>
<divclass="section" id="building-the-docs">
<h3><aclass="toc-backref" href="#contents">Building the docs</a><aclass="headerlink" href="#building-the-docs" title="Permalink to this headline">¶</a></h3>
<p>The documentation sources are found in the <codeclass="file docutils literal notranslate"><spanclass="pre">doc/</span></code> directory in the trunk.
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>
<divclass="highlight-sh notranslate"><divclass="highlight"><pre><span></span>make html
</pre></div>
</div>
<p>Other useful invocations include</p>
<divclass="highlight-sh notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Delete built files. May help if you get errors about missing paths or</span>
<spanclass="c1"># broken links.</span>
make clean
<spanclass="c1"># Build pdf docs.</span>
make latexpdf
</pre></div>
</div>
<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, use</p>
<divclass="highlight-sh notranslate"><divclass="highlight"><pre><span></span>make <spanclass="nv">SPHINXOPTS</span><spanclass="o">=</span> html
</pre></div>
</div>
<p>On Windows the arguments must be at the end of the statement:</p>
<divclass="highlight-bat notranslate"><divclass="highlight"><pre><span></span>make html SPHINXOPTS=
</pre></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><codeclass="docutils literal notranslate"><spanclass="pre">make</span><spanclass="pre">O=-j4</span><spanclass="pre">html</span></code> runs a parallel build with 4 processes.</li>
<li><codeclass="docutils literal notranslate"><spanclass="pre">make</span><spanclass="pre">O=-Dplot_formats=png:100</span><spanclass="pre">html</span></code> saves figures in low resolution.</li>
<li><codeclass="docutils literal notranslate"><spanclass="pre">make</span><spanclass="pre">O=-Dplot_gallery=0</span><spanclass="pre">html</span></code> skips the gallery build.</li>
</ul>
<p>Multiple options can be combined using e.g. <codeclass="docutils literal notranslate"><spanclass="pre">make</span><spanclass="pre">O='-j4</span><spanclass="pre">-Dplot_gallery=0'</span>
<spanclass="pre">html</span></code>.</p>
<p>On Windows, either use the format shown above or set options as environment variables, e.g.:</p>
<spanid="id1"></span><h2><aclass="toc-backref" href="#contents">Writing ReST pages</a><aclass="headerlink" href="#writing-rest-pages" title="Permalink to this headline">¶</a></h2>
<p>Most documentation is either in the docstring 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="http://docutils.sourceforge.net/rst.html">ReST</a> syntax. Users should look at the <aclass="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> documentation
for a full description. But some specific hints and conventions Matplotlib
<h3><aclass="toc-backref" href="#contents">Formatting and style conventions</a><aclass="headerlink" href="#formatting-and-style-conventions" title="Permalink to this headline">¶</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>
<divclass="section" id="section-name-formatting">
<h4><aclass="toc-backref" href="#contents">Section name formatting</a><aclass="headerlink" href="#section-name-formatting" title="Permalink to this headline">¶</a></h4>
<p>For everything but top-level chapters, use <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 <codeclass="docutils literal notranslate"><spanclass="pre">Possible</span>
<spanclass="pre">Hangups</span></code></p>
</div>
<divclass="section" id="function-arguments">
<h4><aclass="toc-backref" href="#contents">Function arguments</a><aclass="headerlink" href="#function-arguments" title="Permalink to this headline">¶</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.
<spanid="internal-section-refs"></span><h3><aclass="toc-backref" href="#contents">Referring to other documents and sections</a><aclass="headerlink" href="#referring-to-other-documents-and-sections" title="Permalink to this headline">¶</a></h3>
<p><aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a> allows internal <aclass="reference external" href="https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html">references</a> between documents.</p>
<p>Documents can be linked with the <codeclass="docutils literal notranslate"><spanclass="pre">:doc:</span></code> directive:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>See the <spanclass="na">:doc:</span><spanclass="nv">`/faq/installing_faq`</span>
See the tutorial <spanclass="na">:doc:</span><spanclass="nv">`/tutorials/introductory/sample_plots`</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="../faq/installing_faq.html"><spanclass="doc">Installation</span></a></p>
<p>See the tutorial <aclass="reference internal" href="../tutorials/introductory/sample_plots.html"><spanclass="doc">Sample plots in Matplotlib</span></a></p>
<p>See the example <aclass="reference internal" href="../gallery/lines_bars_and_markers/simple_plot.html"><spanclass="doc">Simple Plot</span></a></p>
</div></blockquote>
<p>Sections can also be given reference names. For instance from the
<p>will give the following link: <aclass="reference internal" href="../faq/installing_faq.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>
</div>
<divclass="section" id="referring-to-other-code">
<spanid="id2"></span><h3><aclass="toc-backref" href="#contents">Referring to other code</a><aclass="headerlink" href="#referring-to-other-code" title="Permalink to this headline">¶</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 unanbigous 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>.</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><aclass="toc-backref" href="#contents">Including figures and files</a><aclass="headerlink" href="#including-figures-and-files" title="Permalink to this headline">¶</a></h3>
<p>Image files can directly included in pages with the <codeclass="docutils literal notranslate"><spanclass="pre">image::</span></code> directive.
e.g., <codeclass="file docutils literal notranslate"><spanclass="pre">thirdpartypackages/index.rst</span></code> displays the images for the third-party
<p>as rendered on the page: <aclass="reference internal" href="../thirdpartypackages/index.html#thirdparty-index"><spanclass="std std-ref">Third party packages</span></a>.</p>
<p>Files can be included verbatim. For instance the <codeclass="docutils literal notranslate"><spanclass="pre">matplotlibrc</span></code> file
is important for customizing Matplotlib, and is included verbatim in the
tutorial in <aclass="reference internal" href="../tutorials/introductory/customizing.html"><spanclass="doc">Customizing Matplotlib with style sheets and rcParams</span></a>:</p>
<p>This is rendered at the bottom of <aclass="reference internal" href="../tutorials/introductory/customizing.html"><spanclass="doc">Customizing Matplotlib with style sheets and rcParams</span></a>.
Note that this is in a tutorial; see <aclass="reference internal" href="#writing-examples-and-tutorials"><spanclass="std std-ref">Writing examples and tutorials</span></a>
below.</p>
<p>The examples directory is also copied to <codeclass="file docutils literal notranslate"><spanclass="pre">doc/gallery</span></code> by sphinx-gallery,
so plots from the examples directory can be included using</p>
<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>
</div>
</div>
<divclass="section" id="writing-docstrings">
<spanid="id3"></span><h2><aclass="toc-backref" href="#contents">Writing docstrings</a><aclass="headerlink" href="#writing-docstrings" title="Permalink to this headline">¶</a></h2>
<p>Most of the API documentation is written in docstrings. These are comment
blocks in source code that explain how the code works.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">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>All new or edited 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="http://docutils.sourceforge.net/rst.html">ReST</a> syntax discussed above (<aclass="reference internal" href="#writing-rest-pages"><spanclass="std std-ref">Writing ReST pages</span></a>) can be
used for links and references. These 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>
<divclass="section" id="example-docstring">
<h3><aclass="toc-backref" href="#contents">Example docstring</a><aclass="headerlink" href="#example-docstring" title="Permalink to this headline">¶</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>
</div>
<divclass="section" id="formatting-conventions">
<h3><aclass="toc-backref" href="#contents">Formatting conventions</a><aclass="headerlink" href="#formatting-conventions" title="Permalink to this headline">¶</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>
<divclass="section" id="quote-positions">
<h4><aclass="toc-backref" href="#contents">Quote positions</a><aclass="headerlink" href="#quote-positions" title="Permalink to this headline">¶</a></h4>
<p>The quotes for single line docstrings are on the same line (pydocstyle D200):</p>
<spanclass="sd">Set the linestyle of the line.</span>
<spanclass="sd">[...]</span>
<spanclass="sd">"""</span>
</pre></div>
</div>
</div>
<divclass="section" id="id4">
<h4><aclass="toc-backref" href="#contents">Function arguments</a><aclass="headerlink" href="#id4" title="Permalink to this headline">¶</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>If <spanclass="ge">*linestyles*</span> is <spanclass="ge">*None*</span>, the default is 'solid'.
</pre></div>
</div>
<p>Do not use the <codeclass="docutils literal notranslate"><spanclass="pre">`default</span><spanclass="pre">role`</span></code> or the <codeclass="docutils literal notranslate"><spanclass="pre">``literal``</span></code> role:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>Neither <spanclass="nv">`argument`</span> nor <spanclass="s">``argument``</span> should be used.
</pre></div>
</div>
</div>
<divclass="section" id="quotes-for-strings">
<h4><aclass="toc-backref" href="#contents">Quotes for strings</a><aclass="headerlink" href="#quotes-for-strings" title="Permalink to this headline">¶</a></h4>
<p>Matplotlib does not have a convention whether to use single-quotes or
double-quotes. There is a mixture of both in the current code.</p>
<p>Use simple single or double quotes when giving string values, e.g.</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>If 'tight', try to figure out the tight bbox of the figure.
No <spanclass="s">``'extra'``</span> literal quotes.
</pre></div>
</div>
<p>The use of extra literal quotes around the text is discouraged. While they
slightly improve the rendered docs, they are cumbersome to type and difficult
<h4><aclass="toc-backref" href="#contents">Parameter type descriptions</a><aclass="headerlink" href="#parameter-type-descriptions" title="Permalink to this headline">¶</a></h4>
<p>The main goal for parameter type descriptions is to be readable and
understandable by humans. If the possible types are too complex use a
simplification for the type description and explain the type more
precisely in the text.</p>
<p>Generally, the <aclass="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc docstring guide</a> conventions apply. The following
rules expand on them where the numpydoc conventions are not specific.</p>
<p>Use <codeclass="docutils literal notranslate"><spanclass="pre">float</span></code> for a type that can be any number.</p>
<p>Use <codeclass="docutils literal notranslate"><spanclass="pre">(float,</span><spanclass="pre">float)</span></code> to describe a 2D position. The parentheses should be
included to make the tuple-ness more obvious.</p>
<p>Use <codeclass="docutils literal notranslate"><spanclass="pre">array-like</span></code> for homogeneous numeric sequences, which could
typically be a numpy.array. Dimensionality may be specified using <codeclass="docutils literal notranslate"><spanclass="pre">2D</span></code>,
<codeclass="docutils literal notranslate"><spanclass="pre">3D</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">n-dimensional</span></code>. If you need to have variables denoting the
sizes of the dimensions, use capital letters in brackets
(<codeclass="docutils literal notranslate"><spanclass="pre">array-like</span><spanclass="pre">(M,</span><spanclass="pre">N)</span></code>). When referring to them in the text they are easier
read and no special formatting is needed.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">float</span></code> is the implicit default dtype for array-likes. For other dtypes
use <codeclass="docutils literal notranslate"><spanclass="pre">array-like</span><spanclass="pre">of</span><spanclass="pre">int</span></code>.</p>
<p>Non-numeric homogeneous sequences are described as lists, e.g.:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span>list of str
list of `.Artist`
</pre></div>
</div>
</div>
<divclass="section" id="referencing-types">
<h4><aclass="toc-backref" href="#contents">Referencing types</a><aclass="headerlink" href="#referencing-types" title="Permalink to this headline">¶</a></h4>
<p>Generally, the rules from <aclass="reference internal" href="#referring-to-other-code">referring-to-other-code</a> apply. More specifically:</p>
<p>Use full references <codeclass="docutils literal notranslate"><spanclass="pre">`~matplotlib.colors.Normalize`</span></code> with an
abbreviation tilde in parameter types. While the full name helps the
reader of plain text docstrings, the HTML does not need to show the full
name as it links to it. Hence, the <codeclass="docutils literal notranslate"><spanclass="pre">~</span></code>-shortening keeps it more readable.</p>
<p>Use abbreviated links <codeclass="docutils literal notranslate"><spanclass="pre">`.Normalize`</span></code> in the text.</p>
A <spanclass="nv">`.Normalize`</span> instance is used to scale luminance data to 0, 1.
</pre></div>
</div>
</div>
<divclass="section" id="default-values">
<h4><aclass="toc-backref" href="#contents">Default values</a><aclass="headerlink" href="#default-values" title="Permalink to this headline">¶</a></h4>
<p>As opposed to the numpydoc guide, parameters need not be marked as
<em>optional</em> if they have a simple default:</p>
<ulclass="simple">
<li>use <codeclass="docutils literal notranslate"><spanclass="pre">{name}</span><spanclass="pre">:</span><spanclass="pre">{type},</span><spanclass="pre">default:</span><spanclass="pre">{val}</span></code> when possible.</li>
<li>use <codeclass="docutils literal notranslate"><spanclass="pre">{name}</span><spanclass="pre">:</span><spanclass="pre">{type},</span><spanclass="pre">optional</span></code> and describe the default in the text if
it cannot be explained sufficiently in the recommended manner.</li>
</ul>
<p>The default value should provide semantic information targeted at a human
reader. In simple cases, it restates the value in the function signature.
<h4><aclass="toc-backref" href="#contents"><codeclass="docutils literal notranslate"><spanclass="pre">See</span><spanclass="pre">also</span></code> sections</a><aclass="headerlink" href="#see-also-sections" title="Permalink to this headline">¶</a></h4>
<p>Sphinx automatically links code elements in the definition blocks of <codeclass="docutils literal notranslate"><spanclass="pre">See</span>
<spanclass="pre">also</span></code> sections. No need to use backticks there:</p>
<h4><aclass="toc-backref" href="#contents">Wrapping parameter lists</a><aclass="headerlink" href="#wrapping-parameter-lists" title="Permalink to this headline">¶</a></h4>
<p>Long parameter lists should be wrapped using a <codeclass="docutils literal notranslate"><spanclass="pre">\</span></code> for continuation and
starting on the new line without any indent (no indent because pydoc will
parse the docstring and strip the line continuation so that indent would
result in a lot of whitespace within the line):</p>
<spanclass="sd"> The projection type of the axes.</span>
<spanclass="sd"> ...</span>
<spanclass="sd"> """</span>
</pre></div>
</div>
<p>Alternatively, you can describe the valid parameter values in a dedicated
section of the docstring.</p>
</div>
<divclass="section" id="rcparams">
<h4><aclass="toc-backref" href="#contents">rcParams</a><aclass="headerlink" href="#rcparams" title="Permalink to this headline">¶</a></h4>
<p>rcParams can be referenced with the custom <codeclass="docutils literal notranslate"><spanclass="pre">:rc:</span></code> role:
<codeclass="docutils literal notranslate"><spanclass="pre">:rc:`foo`</span></code> yields <codeclass="docutils literal notranslate"><spanclass="pre">rcParams["foo"]</span><spanclass="pre">=</span><spanclass="pre">'default'</span></code>, which is a link
to the <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlibrc</span></code> file description.</p>
</div>
</div>
<divclass="section" id="setters-and-getters">
<h3><aclass="toc-backref" href="#contents">Setters and getters</a><aclass="headerlink" href="#setters-and-getters" title="Permalink to this headline">¶</a></h3>
<p>Artist properties are implemented using setter and getter methods (because
Matplotlib predates the introductions of the <aclass="reference external" href="https://docs.python.org/3/library/functions.html#property" title="(in Python v3.9)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">property</span></code></a> decorator in Python).
By convention, these setters and getters are named <codeclass="docutils literal notranslate"><spanclass="pre">set_PROPERTYNAME</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">get_PROPERTYNAME</span></code>; the list of properties thusly defined on an artist and
their values can be listed by the <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.setp.html#matplotlib.pyplot.setp" title="matplotlib.pyplot.setp"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">setp</span></code></a> and <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.getp.html#matplotlib.pyplot.getp" title="matplotlib.pyplot.getp"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">getp</span></code></a> functions.</p>
<p>The Parameters block of property setter methods is parsed to document the
accepted values, e.g. the docstring of <aclass="reference internal" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D.set_linestyle" title="matplotlib.lines.Line2D.set_linestyle"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Line2D.set_linestyle</span></code></a> starts with</p>
<p>In some rare cases (mostly, setters which accept both a single tuple and an
unpacked tuple), the accepted values cannot be documented in such a fashion;
in that case, they can be documented as an <codeclass="docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">ACCEPTS:</span></code> block, e.g. for
<p>Note that the leading <codeclass="docutils literal notranslate"><spanclass="pre">..</span></code> makes the <codeclass="docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">ACCEPTS:</span></code> block a reST comment,
hiding it from the rendered docs.</p>
</div>
<divclass="section" id="keyword-arguments">
<h3><aclass="toc-backref" href="#contents">Keyword arguments</a><aclass="headerlink" href="#keyword-arguments" title="Permalink to this headline">¶</a></h3>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">The information in this section is being actively discussed by the
development team, so use the docstring interpolation only if necessary.
This section has been left in place for now because this interpolation
is part of the existing documentation.</p>
</div>
<p>Since Matplotlib uses a lot of pass-through <codeclass="docutils literal notranslate"><spanclass="pre">kwargs</span></code>, e.g., in every function
etc...), it can be difficult for the new user to know which <codeclass="docutils literal notranslate"><spanclass="pre">kwargs</span></code> are
supported. Matplotlib uses a docstring interpolation scheme to support
documentation of every function that takes a <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code>. The requirements
are:</p>
<olclass="arabic simple">
<li>single point of configuration so changes to the properties don't
require multiple docstring edits.</li>
<li>as automated as possible so that as properties change, the docs
are updated automatically.</li>
</ol>
<p>The function <aclass="reference internal" href="../api/_as_gen/matplotlib.artist.kwdoc.html#matplotlib.artist.kwdoc" title="matplotlib.artist.kwdoc"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.artist.kwdoc</span></code></a> and the decorator
string interpolation in the docstring with the Matplotlib artist introspection
facility that underlies <codeclass="docutils literal notranslate"><spanclass="pre">setp</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">getp</span></code>. The <codeclass="docutils literal notranslate"><spanclass="pre">kwdoc</span></code> function gives
the list of properties as a docstring. In order to use this in another
docstring, first update the <codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.docstring.interpd</span></code> object, as seen in
this example from <aclass="reference internal" href="../api/lines_api.html#module-matplotlib.lines" title="matplotlib.lines"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.lines</span></code></a>:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in lines.py</span>
<spanclass="sd"> The kwargs are Line2D properties:</span>
<spanclass="sd"> %(_Line2D_docstr)s</span>
<spanclass="sd"> kwargs scalex and scaley, if defined, are passed on</span>
<spanclass="sd"> to autoscale_view to determine whether the x and y axes are</span>
<spanclass="sd"> autoscaled; default True. See Axes.autoscale_view for more</span>
<spanclass="sd"> information</span>
<spanclass="sd"> """</span>
</pre></div>
</div>
<p>Note there is a problem for <aclass="reference internal" href="../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Artist</span></code></a><codeclass="docutils literal notranslate"><spanclass="pre">__init__</span></code> methods,
<h3><aclass="toc-backref" href="#contents">Inheriting docstrings</a><aclass="headerlink" href="#inheriting-docstrings" title="Permalink to this headline">¶</a></h3>
<p>If a subclass overrides a method but does not change the semantics, we can
reuse the parent docstring for the method of the child class. Python does this
automatically, if the subclass method does not have a docstring.</p>
<p>Use a plain comment <codeclass="docutils literal notranslate"><spanclass="pre">#</span><spanclass="pre">docstring</span><spanclass="pre">inherited</span></code> to denote the intention to reuse
the parent docstring. That way we do not accidentally create a docstring in
<spanid="docstring-adding-figures"></span><h3><aclass="toc-backref" href="#contents">Adding figures</a><aclass="headerlink" href="#adding-figures" title="Permalink to this headline">¶</a></h3>
<p>As above (see <aclass="reference internal" href="#rst-figures-and-includes"><spanclass="std std-ref">Including figures and files</span></a>), figures in the examples gallery
can be referenced with a <codeclass="docutils literal notranslate"><spanclass="pre">:plot:</span></code> directive pointing to the python script
that created the figure. For instance the <aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.legend.html#matplotlib.axes.Axes.legend" title="matplotlib.axes.Axes.legend"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">legend</span></code></a> docstring references
the file <codeclass="file docutils literal notranslate"><spanclass="pre">examples/text_labels_and_annotations/legend.py</span></code>:</p>
<p>Note that <codeclass="docutils literal notranslate"><spanclass="pre">examples/text_labels_and_annotations/legend.py</span></code> has been mapped to
<codeclass="docutils literal notranslate"><spanclass="pre">gallery/text_labels_and_annotations/legend.py</span></code>, a redirection that may be
fixed in future re-organization of the docs.</p>
<p>Plots can also be directly placed inside docstrings. Details are in
<aclass="reference internal" href="../api/sphinxext_plot_directive_api.html"><spanclass="doc">matplotlib.sphinxext.plot_directive</span></a>. A short example is:</p>
<spanid="id5"></span><h2><aclass="toc-backref" href="#contents">Writing examples and tutorials</a><aclass="headerlink" href="#writing-examples-and-tutorials" title="Permalink to this headline">¶</a></h2>
<p>Examples and tutorials are python scripts that are run by <aclass="reference external" href="https://sphinx-gallery.readthedocs.io/en/latest/">Sphinx Gallery</a>
to create a gallery of images in the <codeclass="file docutils literal notranslate"><spanclass="pre">/doc/gallery</span></code> and
<codeclass="file docutils literal notranslate"><spanclass="pre">/doc/tutorials</span></code> directories respectively. To exclude an example
from having an plot generated insert "sgskip" somewhere in the filename.</p>
<p>The format of these files is relatively straightforward. Properly
formatted comment blocks are treated as <aclass="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> text, the code is
displayed, and figures are put into the built page.</p>
<p>For instance the example <aclass="reference internal" href="../gallery/lines_bars_and_markers/simple_plot.html"><spanclass="doc">Simple Plot</span></a>
example is generated from
<codeclass="file docutils literal notranslate"><spanclass="pre">/examples/lines_bars_and_markers/simple_plot.py</span></code>, which looks like:</p>
<p>The first comment block is treated as <aclass="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> text. The other comment blocks
render as comments in <aclass="reference internal" href="../gallery/lines_bars_and_markers/simple_plot.html"><spanclass="doc">Simple Plot</span></a>.</p>
<p>Tutorials are made with the exact same mechanism, except they are longer, and
typically have more than one comment block (i.e.
<aclass="reference internal" href="../tutorials/introductory/usage.html"><spanclass="doc">Usage Guide</span></a>). The first comment block
can be the same as the example above. Subsequent blocks of ReST text
are delimited by a line of <codeclass="docutils literal notranslate"><spanclass="pre">###</span></code> characters:</p>
<h3><aclass="toc-backref" href="#contents">Order of examples in the gallery</a><aclass="headerlink" href="#order-of-examples-in-the-gallery" title="Permalink to this headline">¶</a></h3>
<p>The order of the sections of the <aclass="reference internal" href="../tutorials/index.html#tutorials"><spanclass="std std-ref">Tutorials</span></a> and the <aclass="reference internal" href="../gallery/index.html#gallery"><spanclass="std std-ref">Gallery</span></a>, as
well as the order of the examples within each section are determined in a
two step process from within the <codeclass="file docutils literal notranslate"><spanclass="pre">/doc/sphinxext/gallery_order.py</span></code>:</p>
<ulclass="simple">
<li><em>Explicit order</em>: This file contains a list of folders for the section order
and a list of examples for the subsection order. The order of the items
shown in the doc pages is the order those items appear in those lists.</li>
<li><em>Implicit order</em>: If a folder or example is not in those lists, it will be
appended after the explicitly ordered items and all of those additional
items will be ordered by pathname (for the sections) or by filename
(for the subsections).</li>
</ul>
<p>As a consequence, if you want to let your example appear in a certain
position in the gallery, extend those lists with your example.
In case no explicit order is desired or necessary, still make sure
to name your example consistently, i.e. use the main function or subject
of the example as first word in the filename; e.g. an image example
should ideally be named similar to <codeclass="file docutils literal notranslate"><spanclass="pre">imshow_mynewexample.py</span></code>.</p>