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>Writing documentation<aclass="headerlink" href="#writing-documentation" title="Link to this heading">#</a></h1>
<sectionid="getting-started">
<h2>Getting started<aclass="headerlink" href="#getting-started" title="Link to this heading">#</a></h2>
<sectionid="general-file-structure">
<h3>General file structure<aclass="headerlink" href="#general-file-structure" title="Link to this heading">#</a></h3>
<p>All documentation is built from the <codeclass="file docutils literal notranslate"><spanclass="pre">doc/</span></code>. The <codeclass="file docutils literal notranslate"><spanclass="pre">doc/</span></code>
directory contains configuration files for Sphinx and reStructuredText
(<aclass="reference external" href="https://docutils.sourceforge.io/rst.html">ReST</a>; <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code>) files that are rendered to documentation pages.</p>
<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">Writing docstrings</span></a> below.</p>
<p>Second, the contents of <codeclass="file docutils literal notranslate"><spanclass="pre">doc/plot_types</span></code>, <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 python
files in <codeclass="file docutils literal notranslate"><spanclass="pre">plot_types/</span></code>, <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="https://docutils.sourceforge.io/rst.html">ReST</a> documentation built
into their comments. See <aclass="reference internal" href="#writing-examples-and-tutorials"><spanclass="std std-ref">Writing examples and tutorials</span></a> below.</p>
<p>Third, Matplotlib has narrative docs written in <aclass="reference external" href="https://docutils.sourceforge.io/rst.html">ReST</a> in subdirectories of
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/users/</span></code>. If you would like to add new documentation that is suited
to an <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> 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 <codeclass="file docutils literal notranslate"><spanclass="pre">index.rst</span></code> of the subdirectory. See
files in these directories when building documentation.</p>
</div>
</section>
<sectionid="setting-up-the-doc-build">
<h3>Setting up the doc build<aclass="headerlink" href="#setting-up-the-doc-build" title="Link to this heading">#</a></h3>
<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.</p>
<p>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="dependencies.html#doc-dependencies"><spanclass="std std-ref">additional dependencies</span></a> required to
build the documentation.</p>
</section>
<sectionid="building-the-docs">
<h3>Building the docs<aclass="headerlink" href="#building-the-docs" title="Link to this heading">#</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><spanclass="c1"># Build the html documentation, but skip generation of the gallery images to</span>
<spanclass="c1"># save time.</span>
make<spanclass="w"></span>html-noplot
<spanclass="c1"># Delete built files. May help if you get errors about missing paths or</span>
<spanclass="c1"># broken links.</span>
make<spanclass="w"></span>clean
<spanclass="c1"># Build pdf docs.</span>
make<spanclass="w"></span>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
<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">make</span><spanclass="pre">O=-j4</span><spanclass="pre">html</span></code> runs a parallel build with 4 processes.</p></li>
<li><p><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.</p></li>
</ul>
<p>Multiple options can be combined, e.g. <codeclass="docutils literal notranslate"><spanclass="pre">make</span><spanclass="pre">O='-j4</span><spanclass="pre">-Dplot_formats=png:100'</span>
<spanclass="pre">html</span></code>.</p>
<p>On Windows, set the options as environment variables, e.g.:</p>
<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>
</section>
<sectionid="showing-locally-built-docs">
<h3>Showing locally built docs<aclass="headerlink" href="#showing-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="id1"></span><h2>Writing ReST pages<aclass="headerlink" href="#writing-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>
<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>
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="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.
<spanid="internal-section-refs"></span><h3>Referring to other documents and sections<aclass="headerlink" href="#referring-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>
<p>Examples:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span>See the <spanclass="na">:doc:</span><spanclass="nv">`/users/installing/index`</span>
See the tutorial <spanclass="na">:doc:</span><spanclass="nv">`/tutorials/introductory/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="../users/installing/index.html"><spanclass="doc">Installation</span></a></p>
<p>See the tutorial <aclass="reference internal" href="../tutorials/introductory/quick_start.html"><spanclass="doc">Quick start guide</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 labels. For instance from the
<p>will give the following link: <aclass="reference internal" href="../users/installing/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>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>.</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>Including figures and files<aclass="headerlink" href="#including-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>
</section>
<sectionid="writing-docstrings">
<spanid="id3"></span><h2>Writing docstrings<aclass="headerlink" href="#writing-docstrings" title="Link to this heading">#</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="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>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="https://docutils.sourceforge.io/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>
<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>
<spanclass="sd">Set the linestyle of the line.</span>
<spanclass="sd">[...]</span>
<spanclass="sd">"""</span>
</pre></div>
</div>
</section>
<sectionid="id4">
<h4>Function arguments<aclass="headerlink" href="#id4" 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>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>
</section>
<sectionid="quotes-for-strings">
<h4>Quotes for strings<aclass="headerlink" href="#quotes-for-strings" title="Link to this heading">#</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
to read in plain-text docs.</p>
</section>
<sectionid="parameter-type-descriptions">
<h4>Parameter type descriptions<aclass="headerlink" href="#parameter-type-descriptions" title="Link to this heading">#</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">(M,</span><spanclass="pre">N)</span><spanclass="pre">array-like</span></code>). When referring to them in the text they are easier
read and no special formatting is needed. Use <codeclass="docutils literal notranslate"><spanclass="pre">array</span></code> instead of
<codeclass="docutils literal notranslate"><spanclass="pre">array-like</span></code> for return types if the returned object is indeed a numpy array.</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>
A <spanclass="nv">`.Normalize`</span> instance is used to scale luminance data to 0, 1.
</pre></div>
</div>
</section>
<sectionid="default-values">
<h4>Default values<aclass="headerlink" href="#default-values" title="Link to this heading">#</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><p>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.</p></li>
<li><p>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.</p></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><codeclass="docutils literal notranslate"><spanclass="pre">See</span><spanclass="pre">also</span></code> sections<aclass="headerlink" href="#see-also-sections" title="Link to this heading">#</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>
<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>
</section>
<sectionid="rcparams">
<h4>rcParams<aclass="headerlink" href="#rcparams" title="Link to this heading">#</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>
</section>
</section>
<sectionid="setters-and-getters">
<h3>Setters and getters<aclass="headerlink" href="#setters-and-getters" title="Link to this heading">#</a></h3>
<p>Artist properties are implemented using setter and getter methods (because
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