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 (v2.2.2). 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="section" id="getting-started">
<h2>Getting started<aclass="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="general-file-structure">
<h3>General file structure<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> directory. This directory
contains both reStructuredText (<aclass="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a>; <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code>) files that contain pages in
the documentation and configuration files for <aclass="reference external" href="http://www.sphinx-doc.org">Sphinx</a>.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files are kept in <codeclass="file docutils literal notranslate"><spanclass="pre">doc/users</span></code>,
<codeclass="file docutils literal notranslate"><spanclass="pre">doc/devel</span></code>, <codeclass="file docutils literal notranslate"><spanclass="pre">doc/api</span></code> and <codeclass="file docutils literal notranslate"><spanclass="pre">doc/faq</span></code>. 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, developers guide, api reference, and FAQs. 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">docs/gallery</span></code> and <codeclass="file docutils literal notranslate"><spanclass="pre">docs/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. Don’t directly edit the
<codeclass="docutils literal notranslate"><spanclass="pre">.rst</span></code> files in <codeclass="file docutils literal notranslate"><spanclass="pre">docs/gallery</span></code> and <codeclass="file docutils literal notranslate"><spanclass="pre">docs/tutorials</span></code> as they are
regenerated when the documentation are built.</p>
</div>
<divclass="section" id="installing-dependencies">
<h3>Installing dependencies<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. There are several extra
requirements that are needed to build the documentation. They are listed in
<codeclass="file docutils literal notranslate"><spanclass="pre">doc-requirements.txt</span></code> and listed below:</p>
<ulclass="simple">
<li>Sphinx>=1.3, !=1.5.0, !=1.6.4</li>
<li>colorspacious</li>
<li>IPython</li>
<li>mock</li>
<li>numpydoc>=0.4</li>
<li>Pillow</li>
<li>sphinx-gallery>=0.1.12</li>
<li>graphviz</li>
</ul>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<ulclass="last simple">
<li>You’ll need a minimal working LaTeX distribution for many examples to run.</li>
<li><aclass="reference external" href="http://www.graphviz.org/Download.php">Graphviz</a> is not a Python package,
and needs to be installed separately.</li>
</ul>
</div>
</div>
<divclass="section" id="building-the-docs">
<h3>Building the docs<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></code> by default to turn warnings into
errors. 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>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, options needs to be set as environment variables, e.g. <codeclass="docutils literal notranslate"><spanclass="pre">set</span><spanclass="pre">O=-W</span>
<spanid="id1"></span><h2>Writing ReST pages<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>Formatting and style conventions<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>Section name formatting<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>Function arguments<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>Referring to other documents and sections<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="http://www.sphinx-doc.org/en/stable/markup/inline.html">references</a> between documents.</p>
<p>Documents can be linked with the <codeclass="xref py py-obj 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>
<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>. For the full path of the
<p>to get <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>. It is often not
necessary to fully specify the class hierarchy unless there is a namespace
<spanid="rst-figures-and-includes"></span><h3>Including figures and files<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">users/navigation_toolbar.rst</span></code> displays the toolbar icons
<p>as rendered on the page: <aclass="reference internal" href="../users/navigation_toolbar.html#navigation-toolbar"><spanclass="std std-ref">Interactive navigation</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="id2"></span><h2>Writing docstrings<aclass="headerlink" href="#writing-docstrings" title="Permalink to this headline">¶</a></h2>
<p>Much of the documentation lives in “docstrings”. These are comment blocks
in source code that explain how the code works. All new or edited docstrings
should conform to the numpydoc guidelines. These split the docstring into a
number of sections - see the <aclass="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpy documentation howto</a>
for more details and a guide to how docstrings should be formatted. Much of
the <aclass="reference external" href="http://docutils.sourceforge.net/rst.html">ReST</a> syntax discussed above (:ref:writing-rest-pages) 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>Example docstring<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="http://www.sphinx-doc.org/contents.html">documentation</a> concerning ReST
markup and working with Sphinx in general.</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>
</div>
<divclass="section" id="formatting-conventions">
<h3>Formatting conventions<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://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">numpy documentation howto</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>
<ul>
<li><pclass="first">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>
</li>
<li><pclass="first">Long parameter lists should be wrapped using a <codeclass="docutils literal notranslate"><spanclass="pre">\</span></code> for continuation and
<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>
</li>
<li><pclass="first">Generally, do not add markup to types for <codeclass="docutils literal notranslate"><spanclass="pre">Parameters</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Returns</span></code>.
This is usually not needed because Sphinx will link them automatically and
would unnecessarily clutter the docstring. However, it does seem to fail in
some situations. If you encounter such a case, you are allowed to add markup:</p>
<h3>Deprecated formatting conventions<aclass="headerlink" href="#deprecated-formatting-conventions" title="Permalink to this headline">¶</a></h3>
<ulclass="simple">
<li>Formerly, we have used square brackets for explicit parameter lists
<codeclass="docutils literal notranslate"><spanclass="pre">['solid'</span><spanclass="pre">|</span><spanclass="pre">'dashed'</span><spanclass="pre">|</span><spanclass="pre">'dotted']</span></code>. With numpydoc we have switched to their
standard using curly braces <codeclass="docutils literal notranslate"><spanclass="pre">{'solid',</span><spanclass="pre">'dashed',</span><spanclass="pre">'dotted'}</span></code>.</li>
</ul>
</div>
<divclass="section" id="linking-to-other-code">
<h3>Linking to other code<aclass="headerlink" href="#linking-to-other-code" title="Permalink to this headline">¶</a></h3>
<p>To link to other methods, classes, or modules in Matplotlib you can encase
the name to refer to in back ticks, for example:</p>
<h3>Function arguments<aclass="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
<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.
</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>
</div>
<divclass="section" id="setters-and-getters">
<h3>Setters and getters<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.7)"><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 <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">getp</span></code> functions.</p>
<p>Property setter methods should indicate the values they accept using a (legacy)
special block in the docstring, starting with <codeclass="docutils literal notranslate"><spanclass="pre">ACCEPTS</span></code>, as follows:</p>
<divclass="highlight-python notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in lines.py</span>
<p>The ACCEPTS block is used to render a table of all properties and their
acceptable values in the docs; it can also be displayed using, e.g.,
<codeclass="docutils literal notranslate"><spanclass="pre">plt.setp(Line2D)</span></code> (all properties) or <codeclass="docutils literal notranslate"><spanclass="pre">plt.setp(Line2D,</span><spanclass="pre">'linestyle')</span></code>
(just one property).</p>
<p>There are cases in which the ACCEPTS string is not useful in the
generated Sphinx documentation, e.g. if the valid parameters are already
defined in the numpydoc parameter list. You can hide the ACCEPTS string from
Sphinx by making it a ReST comment (i.e. use <codeclass="docutils literal notranslate"><spanclass="pre">..</span><spanclass="pre">ACCEPTS:</span></code>):</p>
<h3>Keyword arguments<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)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,
<spanid="docstring-adding-figures"></span><h3>Adding figures<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="xref py py-obj 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/api/legend.py</span></code>:</p>
<spanid="id4"></span><h2>Writing examples and tutorials<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="xref py py-obj docutils literal notranslate"><spanclass="pre">###</span></code> characters:</p>
<p>In this way text, code, and figures are output in a “notebook” style.</p>
</div>
<divclass="section" id="miscellaneous">
<h2>Miscellaneous<aclass="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="adding-animations">
<h3>Adding animations<aclass="headerlink" href="#adding-animations" title="Permalink to this headline">¶</a></h3>
<p>There is a Matplotlib Google/Gmail account with username <codeclass="docutils literal notranslate"><spanclass="pre">mplgithub</span></code>
which was used to setup the github account but can be used for other
purposes, like hosting Google docs or Youtube videos. You can embed a
Matplotlib animation in the docs by first saving the animation as a
movie using <aclass="reference internal" href="../api/_as_gen/matplotlib.animation.Animation.html#matplotlib.animation.Animation.save" title="matplotlib.animation.Animation.save"><codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">matplotlib.animation.Animation.save()</span></code></a>, and then
uploading to <aclass="reference external" href="https://www.youtube.com/user/matplotlib">matplotlib’s Youtube
channel</a> and inserting the
embedding string youtube provides like:</p>
<divclass="highlight-rst notranslate"><divclass="highlight"><pre><span></span><spanclass="p">..</span><spanclass="ow">raw</span><spanclass="p">::</span> html
<spanid="inheritance-diagrams"></span><h3>Generating inheritance diagrams<aclass="headerlink" href="#generating-inheritance-diagrams" title="Permalink to this headline">¶</a></h3>
<p>Class inheritance diagrams can be generated with the
<codeclass="docutils literal notranslate"><spanclass="pre">inheritance-diagram</span></code> directive. To use it, provide the
directive with a number of class or module names (separated by
whitespace). If a module name is provided, all classes in that module
will be used. All of the ancestors of these classes will be included
in the inheritance diagram.</p>
<p>A single option is available: <em>parts</em> controls how many of parts in
the path to the class are shown. For example, if <em>parts</em> == 1, the
class <codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.patches.Patch</span></code> is shown as <codeclass="docutils literal notranslate"><spanclass="pre">Patch</span></code>. If <em>parts</em>
== 2, it is shown as <codeclass="docutils literal notranslate"><spanclass="pre">patches.Patch</span></code>. If <em>parts</em> == 0, the full
<areashape="rect" id="node1" href="../api/artist_api.html#matplotlib.artist.Artist" target="_top" title="Abstract base class for someone who renders into a" alt="" coords="46,282,135,305"/>
<areashape="rect" id="node2" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D" target="_top" title="A line - the line can have both a solid linestyle connecting all" alt="" coords="225,236,321,259"/>
<areashape="rect" id="node7" href="../api/_as_gen/matplotlib.patches.Patch.html#matplotlib.patches.Patch" target="_top" title="A patch is a 2D artist with a face color and an edge color." alt="" coords="221,282,325,305"/>
<areashape="rect" id="node25" href="../api/text_api.html#matplotlib.text.Text" target="_top" title="Handle storing and drawing of text in window or data coordinates." alt="" coords="236,535,310,559"/>
<areashape="rect" id="node3" href="../api/_as_gen/matplotlib.lines.VertexSelector.html#matplotlib.lines.VertexSelector" target="_top" title="Manage the callbacks to maintain a list of selected vertices for" alt="" coords="19,236,161,259"/>
<areashape="rect" id="node4" href="../api/_as_gen/matplotlib.patches.Arc.html#matplotlib.patches.Arc" target="_top" title="An elliptical arc.  Because it performs various optimizations, it" alt="" coords="630,5,722,29"/>
<areashape="rect" id="node14" href="../api/_as_gen/matplotlib.patches.FancyArrowPatch.html#matplotlib.patches.FancyArrowPatch" target="_top" title="A fancy arrow patch. It draws an arrow using the :class:`ArrowStyle`." alt="" coords="370,166,545,190"/>
<areashape="rect" id="node17" href="../api/_as_gen/matplotlib.patches.Polygon.html#matplotlib.patches.Polygon" target="_top" title="A general polygon patch." alt="" coords="397,212,518,236"/>
<areashape="rect" id="node18" href="../api/_as_gen/matplotlib.patches.FancyBboxPatch.html#matplotlib.patches.FancyBboxPatch" target="_top" title="Draw a fancy box around a rectangle with lower left at *xy*=(*x*," alt="" coords="372,258,543,282"/>
<areashape="rect" id="node20" href="../api/_as_gen/matplotlib.patches.Rectangle.html#matplotlib.patches.Rectangle" target="_top" title="Draw a rectangle with lower left at *xy* = (*x*, *y*) with" alt="" coords="391,350,524,374"/>
<areashape="rect" id="node23" href="../api/_as_gen/matplotlib.patches.YAArrow.html#matplotlib.patches.YAArrow" target="_top" title="Yet another arrow class." alt="" coords="396,489,519,512"/>
<areashape="rect" id="node8" href="../api/_as_gen/matplotlib.patches.ArrowStyle.html#matplotlib.patches.ArrowStyle" target="_top" title=":class:`ArrowStyle` is a container class which defines several" alt="" coords="21,190,160,213"/>
<areashape="rect" id="node9" href="../api/_as_gen/matplotlib.patches.BoxStyle.html#matplotlib.patches.BoxStyle" target="_top" title=":class:`BoxStyle` is a container class which defines several" alt="" coords="27,143,153,167"/>
<areashape="rect" id="node11" href="../api/_as_gen/matplotlib.patches.CirclePolygon.html#matplotlib.patches.CirclePolygon" target="_top" title="A polygon-approximation of a circle patch." alt="" coords="598,120,754,143"/>
<areashape="rect" id="node13" href="../api/_as_gen/matplotlib.patches.ConnectionPatch.html#matplotlib.patches.ConnectionPatch" target="_top" title="A :class:`~matplotlib.patches.ConnectionPatch` class is to make" alt="" coords="590,166,763,190"/>
<areashape="rect" id="node15" href="../api/_as_gen/matplotlib.patches.ConnectionStyle.html#matplotlib.patches.ConnectionStyle" target="_top" title=":class:`ConnectionStyle` is a container class which defines" alt="" coords="5,97,176,121"/>
<areashape="rect" id="node16" href="../api/_as_gen/matplotlib.patches.FancyArrow.html#matplotlib.patches.FancyArrow" target="_top" title="Like Arrow, but lets you set head width and head height independently." alt="" coords="605,212,747,236"/>
<areashape="rect" id="node27" href="../api/text_api.html#matplotlib.text.TextWithDash" target="_top" title="This is basically a :class:`~matplotlib.text.Text` with a dash" alt="" coords="391,581,524,605"/>
<areashape="rect" id="node26" href="../api/text_api.html#matplotlib.text.OffsetFrom" target="_top" title="Callable helper class for working with `Annotation`" alt="" coords="33,51,148,75"/>
</map></div>
<divclass="section" id="emacs-helpers">
<spanid="id5"></span><h3>Emacs helpers<aclass="headerlink" href="#emacs-helpers" title="Permalink to this headline">¶</a></h3>
<p>There is an emacs mode <aclass="reference external" href="http://docutils.sourceforge.net/tools/editors/emacs/rst.el">rst.el</a> which
automates many important ReST tasks like building and updating
table-of-contents, and promoting or demoting section headings. Here
is the basic <codeclass="docutils literal notranslate"><spanclass="pre">.emacs</span></code> configuration:</p>