pandas/guide/pandas_docstring.html


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>pandas docstring guide &#8212; Python  documentation</title>
    <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript" src="_static/documentation_options.js"></script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Submitting your changes" href="pandas_pr.html" />
    <link rel="prev" title="Before the sprint: Set up instructions" href="pandas_setup.html" />
   
  <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="pandas-docstring-guide">
<span id="docstring"></span><h1>pandas docstring guide<a class="headerlink" href="#pandas-docstring-guide" title="Permalink to this headline">¶</a></h1>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference external" href="https://www.youtube.com/watch?v=EOA0lUeW4NI">Video tutorial: Pandas docstring guide</a> by Frank Akogun.</p>
</div>
<div class="section" id="about-docstrings-and-standards">
<h2>About docstrings and standards<a class="headerlink" href="#about-docstrings-and-standards" title="Permalink to this headline">¶</a></h2>
<p>A Python docstring is a string used to document a Python module, class,
function or method, so programmers can understand what it does without having
to read the details of the implementation.</p>
<p>Also, it is a common practice to generate online (html) documentation
automatically from docstrings. <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> serves
this purpose.</p>
<p>Next example gives an idea on how a docstring looks like:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="n">num1</span><span class="p">,</span> <span class="n">num2</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd">Add up two integer numbers.</span>

<span class="sd">This function simply wraps the `+` operator, and does not</span>
<span class="sd">do anything interesting, except for illustrating what is</span>
<span class="sd">the docstring of a very simple function.</span>

<span class="sd">Parameters</span>
<span class="sd">----------</span>
<span class="sd">num1 : int</span>
<span class="sd">    First number to add</span>
<span class="sd">num2 : int</span>
<span class="sd">    Second number to add</span>

<span class="sd">Returns</span>
<span class="sd">-------</span>
<span class="sd">int</span>
<span class="sd">    The sum of `num1` and `num2`</span>

<span class="sd">See Also</span>
<span class="sd">--------</span>
<span class="sd">subtract : Subtract one integer from another</span>

<span class="sd">Examples</span>
<span class="sd">--------</span>
<span class="sd">&gt;&gt;&gt; add(2, 2)</span>
<span class="sd">4</span>
<span class="sd">&gt;&gt;&gt; add(25, 0)</span>
<span class="sd">25</span>
<span class="sd">&gt;&gt;&gt; add(10, -10)</span>
<span class="sd">0</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="k">return</span> <span class="n">num1</span> <span class="o">+</span> <span class="n">num2</span>
</pre></div>
</div>
<p>Some standards exist about docstrings, so they are easier to read, and they can
be exported to other formats such as html or pdf.</p>
<p>The first conventions every Python docstring should follow are defined in
<a class="reference external" href="https://www.python.org/dev/peps/pep-0257/">PEP-257</a>.</p>
<p>As PEP-257 is quite open, and some other standards exist on top of it. In the
case of pandas, the numpy docstring convention is followed. The conventions is
explained in this document:</p>
<ul class="simple">
<li><a class="reference external" href="http://numpydoc.readthedocs.io/en/latest/format.html">numpydoc docstring guide</a>
(which is based in the original <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">Guide to NumPy/SciPy documentation</a>)</li>
</ul>
<p>numpydoc is a Sphinx extension to support the numpy docstring convention.</p>
<p>The standard uses reStructuredText (reST). reStructuredText is a markup
language that allows encoding styles in plain text files. Documentation
about reStructuredText can be found in:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.sphinx-doc.org/en/stable/rest.html">Sphinx reStructuredText primer</a></li>
<li><a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">Quick reStructuredText reference</a></li>
<li><a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">Full reStructuredText specification</a></li>
</ul>
<p>The rest of this document will summarize all the above guides, and will
provide additional convention specific to the pandas project.</p>
</div>
<div class="section" id="writing-a-docstring">
<span id="docstring-tutorial"></span><h2>Writing a docstring<a class="headerlink" href="#writing-a-docstring" title="Permalink to this headline">¶</a></h2>
<div class="section" id="general-rules">
<span id="docstring-general"></span><h3>General rules<a class="headerlink" href="#general-rules" title="Permalink to this headline">¶</a></h3>
<p>Docstrings must be defined with three double-quotes. No blank lines should be
left before or after the docstring. The text starts in the next line after the
opening quotes. The closing quotes have their own line
(meaning that they are not at the end of the last sentence).</p>
<p>In rare occasions reST styles like bold text or itallics will be used in
docstrings, but is it common to have inline code, which is presented between
backticks. It is considered inline code:</p>
<ul class="simple">
<li>The name of a parameter</li>
<li>Python code, a module, function, built-in, type, literal… (e.g. <code class="docutils literal notranslate"><span class="pre">os</span></code>,
<code class="docutils literal notranslate"><span class="pre">list</span></code>, <code class="docutils literal notranslate"><span class="pre">numpy.abs</span></code>, <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code>, <code class="docutils literal notranslate"><span class="pre">True</span></code>)</li>
<li>A pandas class (in the form <code class="docutils literal notranslate"><span class="pre">:class:`pandas.Series`</span></code>)</li>
<li>A pandas method (in the form <code class="docutils literal notranslate"><span class="pre">:meth:`pandas.Series.sum`</span></code>)</li>
<li>A pandas function (in the form <code class="docutils literal notranslate"><span class="pre">:func:`pandas.to_datetime`</span></code>)</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To display only the last component of the linked class, method or
function, prefix it with <code class="docutils literal notranslate"><span class="pre">~</span></code>. For example, <code class="docutils literal notranslate"><span class="pre">:class:`~pandas.Series`</span></code>
will link to <code class="docutils literal notranslate"><span class="pre">pandas.Series</span></code> but only display the last part, <code class="docutils literal notranslate"><span class="pre">Series</span></code>
as the link text. See <a class="reference external" href="http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-syntax">Sphinx cross-referencing syntax</a>
for details.</p>
</div>
<p><strong>Good:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">add_values</span><span class="p">(</span><span class="n">arr</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Add the values in `arr`.</span>

<span class="sd">    This is equivalent to Python `sum` of :meth:`pandas.Series.sum`.</span>

<span class="sd">    Some sections are omitted here for simplicity.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="n">arr</span><span class="p">)</span>
</pre></div>
</div>
<p><strong>Bad:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">func</span><span class="p">():</span>

    <span class="sd">&quot;&quot;&quot;Some function.</span>

<span class="sd">    With several mistakes in the docstring.</span>

<span class="sd">    It has a blank like after the signature `def func():`.</span>

<span class="sd">    The text &#39;Some function&#39; should go in the line after the</span>
<span class="sd">    opening quotes of the docstring, not in the same line.</span>

<span class="sd">    There is a blank line between the docstring and the first line</span>
<span class="sd">    of code `foo = 1`.</span>

<span class="sd">    The closing quotes should be in the next line, not in this one.&quot;&quot;&quot;</span>

    <span class="n">foo</span> <span class="o">=</span> <span class="mi">1</span>
    <span class="n">bar</span> <span class="o">=</span> <span class="mi">2</span>
    <span class="k">return</span> <span class="n">foo</span> <span class="o">+</span> <span class="n">bar</span>
</pre></div>
</div>
</div>
<div class="section" id="section-1-short-summary">
<span id="docstring-short-summary"></span><h3>Section 1: Short summary<a class="headerlink" href="#section-1-short-summary" title="Permalink to this headline">¶</a></h3>
<p>The short summary is a single sentence that expresses what the function does in
a concise way.</p>
<p>The short summary must start with a capital letter, end with a dot, and fit in
a single line. It needs to express what the object does without providing
details. For functions and methods, the short summary must start with an
infinitive verb.</p>
<p><strong>Good:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">astype</span><span class="p">(</span><span class="n">dtype</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Cast Series type.</span>

<span class="sd">    This section will provide further details.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>
</pre></div>
</div>
<p><strong>Bad:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">astype</span><span class="p">(</span><span class="n">dtype</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Casts Series type.</span>

<span class="sd">    Verb in third-person of the present simple, should be infinitive.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>

<span class="k">def</span> <span class="nf">astype</span><span class="p">(</span><span class="n">dtype</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Method to cast Series type.</span>

<span class="sd">    Does not start with verb.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>

<span class="k">def</span> <span class="nf">astype</span><span class="p">(</span><span class="n">dtype</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Cast Series type</span>

<span class="sd">    Missing dot at the end.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>

<span class="k">def</span> <span class="nf">astype</span><span class="p">(</span><span class="n">dtype</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Cast Series type from its current type to the new type defined in</span>
<span class="sd">    the parameter dtype.</span>

<span class="sd">    Summary is too verbose and doesn&#39;t fit in a single line.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="section-2-extended-summary">
<span id="docstring-extended-summary"></span><h3>Section 2: Extended summary<a class="headerlink" href="#section-2-extended-summary" title="Permalink to this headline">¶</a></h3>
<p>The extended summary provides details on what the function does. It should not
go into the details of the parameters, or discuss implementation notes, which
go in other sections.</p>
<p>A blank line is left between the short summary and the extended summary. And
every paragraph in the extended summary is finished by a dot.</p>
<p>The extended summary should provide details on why the function is useful and
their use cases, if it is not too generic.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">unstack</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Pivot a row index to columns.</span>

<span class="sd">    When using a multi-index, a level can be pivoted so each value in</span>
<span class="sd">    the index becomes a column. This is especially useful when a subindex</span>
<span class="sd">    is repeated for the main index, and data is easier to visualize as a</span>
<span class="sd">    pivot table.</span>

<span class="sd">    The index level will be automatically removed from the index when added</span>
<span class="sd">    as columns.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="section-3-parameters">
<span id="docstring-parameters"></span><h3>Section 3: Parameters<a class="headerlink" href="#section-3-parameters" title="Permalink to this headline">¶</a></h3>
<p>The details of the parameters will be added in this section. This section has
the title “Parameters”, followed by a line with a hyphen under each letter of
the word “Parameters”. A blank line is left before the section title, but not
after, and not between the line with the word “Parameters” and the one with
the hyphens.</p>
<p>After the title, each parameter in the signature must be documented, including
<cite>*args</cite> and <cite>**kwargs</cite>, but not <cite>self</cite>.</p>
<p>The parameters are defined by their name, followed by a space, a colon, another
space, and the type (or types). Note that the space between the name and the
colon is important. Types are not defined for <cite>*args</cite> and <cite>**kwargs</cite>, but must
be defined for all other parameters. After the parameter definition, it is
required to have a line with the parameter description, which is indented, and
can have multiple lines. The description must start with a capital letter, and
finish with a dot.</p>
<p>For keyword arguments with a default value, the default will be listed after a
comma at the end of the type. The exact form of the type in this case will be
“int, default 0”. In some cases it may be useful to explain what the default
argument means, which can be added after a comma “int, default -1, meaning all
cpus”.</p>
<p>In cases where the default value is <cite>None</cite>, meaning that the value will not be
used. Instead of “str, default None”, it is preferred to write “str, optional”.
When <cite>None</cite> is a value being used, we will keep the form “str, default None”.
For example, in <cite>df.to_csv(compression=None)</cite>, <cite>None</cite> is not a value being used,
but means that compression is optional, and no compression is being used if not
provided. In this case we will use <cite>str, optional</cite>. Only in cases like
<cite>func(value=None)</cite> and <cite>None</cite> is being used in the same way as <cite>0</cite> or <cite>foo</cite>
would be used, then we will specify “str, int or None, default None”.</p>
<p><strong>Good:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Series</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">plot</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">kind</span><span class="p">,</span> <span class="n">color</span><span class="o">=</span><span class="s1">&#39;blue&#39;</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Generate a plot.</span>

<span class="sd">        Render the data in the Series as a matplotlib plot of the</span>
<span class="sd">        specified kind.</span>

<span class="sd">        Parameters</span>
<span class="sd">        ----------</span>
<span class="sd">        kind : str</span>
<span class="sd">            Kind of matplotlib plot.</span>
<span class="sd">        color : str, default &#39;blue&#39;</span>
<span class="sd">            Color name or rgb code.</span>
<span class="sd">        **kwargs</span>
<span class="sd">            These parameters will be passed to the matplotlib plotting</span>
<span class="sd">            function.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>
</pre></div>
</div>
<p><strong>Bad:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Series</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">plot</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">kind</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Generate a plot.</span>

<span class="sd">        Render the data in the Series as a matplotlib plot of the</span>
<span class="sd">        specified kind.</span>

<span class="sd">        Note the blank line between the parameters title and the first</span>
<span class="sd">        parameter. Also, note that after the name of the parameter `kind`</span>
<span class="sd">        and before the colon, a space is missing.</span>

<span class="sd">        Also, note that the parameter descriptions do not start with a</span>
<span class="sd">        capital letter, and do not finish with a dot.</span>

<span class="sd">        Finally, the `**kwargs` parameter is missing.</span>

<span class="sd">        Parameters</span>
<span class="sd">        ----------</span>

<span class="sd">        kind: str</span>
<span class="sd">            kind of matplotlib plot</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>
</pre></div>
</div>
<div class="section" id="parameter-types">
<span id="docstring-parameter-types"></span><h4>Parameter types<a class="headerlink" href="#parameter-types" title="Permalink to this headline">¶</a></h4>
<p>When specifying the parameter types, Python built-in data types can be used
directly (the Python type is preferred to the more verbose string, integer,
boolean, etc):</p>
<ul class="simple">
<li>int</li>
<li>float</li>
<li>str</li>
<li>bool</li>
</ul>
<p>For complex types, define the subtypes. For <cite>dict</cite> and <cite>tuple</cite>, as more than
one type is present, we use the brackets to help read the type (curly brackets
for <cite>dict</cite> and normal brackets for <cite>tuple</cite>):</p>
<ul class="simple">
<li>list of int</li>
<li>dict of {str : int}</li>
<li>tuple of (str, int, int)</li>
<li>tuple of (str,)</li>
<li>set of str</li>
</ul>
<p>In case where there are just a set of values allowed, list them in curly
brackets and separated by commas (followed by a space). If the values are
ordinal and they have an order, list them in this order. Otherwise, list
the default value first, if there is one:</p>
<ul class="simple">
<li>{0, 10, 25}</li>
<li>{‘simple’, ‘advanced’}</li>
<li>{‘low’, ‘medium’, ‘high’}</li>
<li>{‘cat’, ‘dog’, ‘bird’}</li>
</ul>
<p>If the type is defined in a Python module, the module must be specified:</p>
<ul class="simple">
<li>datetime.date</li>
<li>datetime.datetime</li>
<li>decimal.Decimal</li>
</ul>
<p>If the type is in a package, the module must be also specified:</p>
<ul class="simple">
<li>numpy.ndarray</li>
<li>scipy.sparse.coo_matrix</li>
</ul>
<p>If the type is a pandas type, also specify pandas except for Series and
DataFrame:</p>
<ul class="simple">
<li>Series</li>
<li>DataFrame</li>
<li>pandas.Index</li>
<li>pandas.Categorical</li>
<li>pandas.SparseArray</li>
</ul>
<p>If the exact type is not relevant, but must be compatible with a numpy
array, array-like can be specified. If Any type that can be iterated is
accepted, iterable can be used:</p>
<ul class="simple">
<li>array-like</li>
<li>iterable</li>
</ul>
<p>If more than one type is accepted, separate them by commas, except the
last two types, that need to be separated by the word ‘or’:</p>
<ul class="simple">
<li>int or float</li>
<li>float, decimal.Decimal or None</li>
<li>str or list of str</li>
</ul>
<p>If <code class="docutils literal notranslate"><span class="pre">None</span></code> is one of the accepted values, it always needs to be the last in
the list.</p>
<p>For axis, the convention is to use something like:</p>
<ul class="simple">
<li>axis : {0 or ‘index’, 1 or ‘columns’, None}, default None</li>
</ul>
</div>
</div>
<div class="section" id="section-4-returns-or-yields">
<span id="docstring-returns"></span><h3>Section 4: Returns or Yields<a class="headerlink" href="#section-4-returns-or-yields" title="Permalink to this headline">¶</a></h3>
<p>If the method returns a value, it will be documented in this section. Also
if the method yields its output.</p>
<p>The title of the section will be defined in the same way as the “Parameters”.
With the names “Returns” or “Yields” followed by a line with as many hyphens
as the letters in the preceding word.</p>
<p>The documentation of the return is also similar to the parameters. But in this
case, no name will be provided, unless the method returns or yields more than
one value (a tuple of values).</p>
<p>The types for “Returns” and “Yields” are the same as the ones for the
“Parameters”. Also, the description must finish with a dot.</p>
<p>For example, with a single value:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">sample</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Generate and return a random number.</span>

<span class="sd">    The value is sampled from a continuous uniform distribution between</span>
<span class="sd">    0 and 1.</span>

<span class="sd">    Returns</span>
<span class="sd">    -------</span>
<span class="sd">    float</span>
<span class="sd">        Random number generated.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">return</span> <span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">()</span>
</pre></div>
</div>
<p>With more than one value:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">random_letters</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Generate and return a sequence of random letters.</span>

<span class="sd">    The length of the returned string is also random, and is also</span>
<span class="sd">    returned.</span>

<span class="sd">    Returns</span>
<span class="sd">    -------</span>
<span class="sd">    length : int</span>
<span class="sd">        Length of the returned string.</span>
<span class="sd">    letters : str</span>
<span class="sd">        String of random letters.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">length</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
    <span class="n">letters</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">string</span><span class="o">.</span><span class="n">ascii_lowercase</span><span class="p">)</span>
                      <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">length</span><span class="p">))</span>
    <span class="k">return</span> <span class="n">length</span><span class="p">,</span> <span class="n">letters</span>
</pre></div>
</div>
<p>If the method yields its value:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">sample_values</span><span class="p">():</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Generate an infinite sequence of random numbers.</span>

<span class="sd">    The values are sampled from a continuous uniform distribution between</span>
<span class="sd">    0 and 1.</span>

<span class="sd">    Yields</span>
<span class="sd">    ------</span>
<span class="sd">    float</span>
<span class="sd">        Random number generated.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
        <span class="k">yield</span> <span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="section-5-see-also">
<span id="docstring-see-also"></span><h3>Section 5: See Also<a class="headerlink" href="#section-5-see-also" title="Permalink to this headline">¶</a></h3>
<p>This section is used to let users know about pandas functionality
related to the one being documented. In rare cases, if no related methods
or functions can be found at all, this section can be skipped.</p>
<p>An obvious example would be the <cite>head()</cite> and <cite>tail()</cite> methods. As <cite>tail()</cite> does
the equivalent as <cite>head()</cite> but at the end of the <cite>Series</cite> or <cite>DataFrame</cite>
instead of at the beginning, it is good to let the users know about it.</p>
<p>To give an intuition on what can be considered related, here there are some
examples:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">loc</span></code> and <code class="docutils literal notranslate"><span class="pre">iloc</span></code>, as they do the same, but in one case providing indices
and in the other positions</li>
<li><code class="docutils literal notranslate"><span class="pre">max</span></code> and <code class="docutils literal notranslate"><span class="pre">min</span></code>, as they do the opposite</li>
<li><code class="docutils literal notranslate"><span class="pre">iterrows</span></code>, <code class="docutils literal notranslate"><span class="pre">itertuples</span></code> and <code class="docutils literal notranslate"><span class="pre">iteritems</span></code>, as it is easy that a user
looking for the method to iterate over columns ends up in the method to
iterate over rows, and vice-versa</li>
<li><code class="docutils literal notranslate"><span class="pre">fillna</span></code> and <code class="docutils literal notranslate"><span class="pre">dropna</span></code>, as both methods are used to handle missing values</li>
<li><code class="docutils literal notranslate"><span class="pre">read_csv</span></code> and <code class="docutils literal notranslate"><span class="pre">to_csv</span></code>, as they are complementary</li>
<li><code class="docutils literal notranslate"><span class="pre">merge</span></code> and <code class="docutils literal notranslate"><span class="pre">join</span></code>, as one is a generalization of the other</li>
<li><code class="docutils literal notranslate"><span class="pre">astype</span></code> and <code class="docutils literal notranslate"><span class="pre">pandas.to_datetime</span></code>, as users may be reading the
documentation of <code class="docutils literal notranslate"><span class="pre">astype</span></code> to know how to cast as a date, and the way to do
it is with <code class="docutils literal notranslate"><span class="pre">pandas.to_datetime</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">where</span></code> is related to <code class="docutils literal notranslate"><span class="pre">numpy.where</span></code>, as its functionality is based on it</li>
</ul>
<p>When deciding what is related, you should mainly use your common sense and
think about what can be useful for the users reading the documentation,
especially the less experienced ones.</p>
<p>When relating to other libraries (mainly <code class="docutils literal notranslate"><span class="pre">numpy</span></code>), use the name of the module
first (not an alias like <code class="docutils literal notranslate"><span class="pre">np</span></code>). If the function is in a module which is not
the main one, like <code class="docutils literal notranslate"><span class="pre">scipy.sparse</span></code>, list the full module (e.g.
<code class="docutils literal notranslate"><span class="pre">scipy.sparse.coo_matrix</span></code>).</p>
<p>This section, as the previous, also has a header, “See Also” (note the capital
S and A). Also followed by the line with hyphens, and preceded by a blank line.</p>
<p>After the header, we will add a line for each related method or function,
followed by a space, a colon, another space, and a short description that
illustrated what this method or function does, why is it relevant in this
context, and what are the key differences between the documented function and
the one referencing. The description must also finish with a dot.</p>
<p>Note that in “Returns” and “Yields”, the description is located in the
following line than the type. But in this section it is located in the same
line, with a colon in between. If the description does not fit in the same
line, it can continue in the next ones, but it has to be indented in them.</p>
<p>For example:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Series</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">head</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return the first 5 elements of the Series.</span>

<span class="sd">        This function is mainly useful to preview the values of the</span>
<span class="sd">        Series without displaying the whole of it.</span>

<span class="sd">        Returns</span>
<span class="sd">        -------</span>
<span class="sd">        Series</span>
<span class="sd">            Subset of the original series with the 5 first values.</span>

<span class="sd">        See Also</span>
<span class="sd">        --------</span>
<span class="sd">        Series.tail : Return the last 5 elements of the Series.</span>
<span class="sd">        Series.iloc : Return a slice of the elements in the Series,</span>
<span class="sd">            which can also be used to return the first or last n.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">iloc</span><span class="p">[:</span><span class="mi">5</span><span class="p">]</span>
</pre></div>
</div>
</div>
<div class="section" id="section-6-notes">
<span id="docstring-notes"></span><h3>Section 6: Notes<a class="headerlink" href="#section-6-notes" title="Permalink to this headline">¶</a></h3>
<p>This is an optional section used for notes about the implementation of the
algorithm. Or to document technical aspects of the function behavior.</p>
<p>Feel free to skip it, unless you are familiar with the implementation of the
algorithm, or you discover some counter-intuitive behavior while writing the
examples for the function.</p>
<p>This section follows the same format as the extended summary section.</p>
</div>
<div class="section" id="section-7-examples">
<span id="docstring-examples"></span><h3>Section 7: Examples<a class="headerlink" href="#section-7-examples" title="Permalink to this headline">¶</a></h3>
<p>This is one of the most important sections of a docstring, even if it is
placed in the last position. As often, people understand concepts better
with examples, than with accurate explanations.</p>
<p>Examples in docstrings, besides illustrating the usage of the function or
method, must be valid Python code, that in a deterministic way returns the
presented output, and that can be copied and run by users.</p>
<p>They are presented as a session in the Python terminal. <cite>&gt;&gt;&gt;</cite> is used to
present code. <cite>…</cite> is used for code continuing from the previous line.
Output is presented immediately after the last line of code generating the
output (no blank lines in between). Comments describing the examples can
be added with blank lines before and after them.</p>
<p>The way to present examples is as follows:</p>
<ol class="arabic simple">
<li>Import required libraries (except <code class="docutils literal notranslate"><span class="pre">numpy</span></code> and <code class="docutils literal notranslate"><span class="pre">pandas</span></code>)</li>
<li>Create the data required for the example</li>
<li>Show a very basic example that gives an idea of the most common use case</li>
<li>Add examples with explanations that illustrate how the parameters can be
used for extended functionality</li>
</ol>
<p>A simple example could be:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Series</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">head</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">n</span><span class="o">=</span><span class="mi">5</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return the first elements of the Series.</span>

<span class="sd">        This function is mainly useful to preview the values of the</span>
<span class="sd">        Series without displaying the whole of it.</span>

<span class="sd">        Parameters</span>
<span class="sd">        ----------</span>
<span class="sd">        n : int</span>
<span class="sd">            Number of values to return.</span>

<span class="sd">        Return</span>
<span class="sd">        ------</span>
<span class="sd">        pandas.Series</span>
<span class="sd">            Subset of the original series with the n first values.</span>

<span class="sd">        See Also</span>
<span class="sd">        --------</span>
<span class="sd">        tail : Return the last n elements of the Series.</span>

<span class="sd">        Examples</span>
<span class="sd">        --------</span>
<span class="sd">        &gt;&gt;&gt; s = pd.Series([&#39;Ant&#39;, &#39;Bear&#39;, &#39;Cow&#39;, &#39;Dog&#39;, &#39;Falcon&#39;,</span>
<span class="sd">        ...                &#39;Lion&#39;, &#39;Monkey&#39;, &#39;Rabbit&#39;, &#39;Zebra&#39;])</span>
<span class="sd">        &gt;&gt;&gt; s.head()</span>
<span class="sd">        0   Ant</span>
<span class="sd">        1   Bear</span>
<span class="sd">        2   Cow</span>
<span class="sd">        3   Dog</span>
<span class="sd">        4   Falcon</span>
<span class="sd">        dtype: object</span>

<span class="sd">        With the `n` parameter, we can change the number of returned rows:</span>

<span class="sd">        &gt;&gt;&gt; s.head(n=3)</span>
<span class="sd">        0   Ant</span>
<span class="sd">        1   Bear</span>
<span class="sd">        2   Cow</span>
<span class="sd">        dtype: object</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">iloc</span><span class="p">[:</span><span class="n">n</span><span class="p">]</span>
</pre></div>
</div>
<p>The examples should be as concise as possible. In cases where the complexity of
the function requires long examples, is recommended to use blocks with headers
in bold. Use double star <code class="docutils literal notranslate"><span class="pre">**</span></code> to make a text bold, like in <code class="docutils literal notranslate"><span class="pre">**this</span> <span class="pre">example**</span></code>.</p>
<div class="section" id="conventions-for-the-examples">
<span id="docstring-example-conventions"></span><h4>Conventions for the examples<a class="headerlink" href="#conventions-for-the-examples" title="Permalink to this headline">¶</a></h4>
<p>Code in examples is assumed to always start with these two lines which are not
shown:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">pandas</span> <span class="kn">as</span> <span class="nn">pd</span>
</pre></div>
</div>
<p>Any other module used in the examples must be explicitly imported, one per line (as
recommended in <a class="reference external" href="https://www.python.org/dev/peps/pep-0008/#imports">PEP-8</a>)
and avoiding aliases. Avoid excessive imports, but if needed, imports from
the standard library go first, followed by third-party libraries (like
matplotlib).</p>
<p>When illustrating examples with a single <code class="docutils literal notranslate"><span class="pre">Series</span></code> use the name <code class="docutils literal notranslate"><span class="pre">s</span></code>, and if
illustrating with a single <code class="docutils literal notranslate"><span class="pre">DataFrame</span></code> use the name <code class="docutils literal notranslate"><span class="pre">df</span></code>. For indices,
<code class="docutils literal notranslate"><span class="pre">idx</span></code> is the preferred name. If a set of homogeneous <code class="docutils literal notranslate"><span class="pre">Series</span></code> or
<code class="docutils literal notranslate"><span class="pre">DataFrame</span></code> is used, name them <code class="docutils literal notranslate"><span class="pre">s1</span></code>, <code class="docutils literal notranslate"><span class="pre">s2</span></code>, <code class="docutils literal notranslate"><span class="pre">s3</span></code>…  or <code class="docutils literal notranslate"><span class="pre">df1</span></code>,
<code class="docutils literal notranslate"><span class="pre">df2</span></code>, <code class="docutils literal notranslate"><span class="pre">df3</span></code>… If the data is not homogeneous, and more than one structure
is needed, name them with something meaningful, for example <code class="docutils literal notranslate"><span class="pre">df_main</span></code> and
<code class="docutils literal notranslate"><span class="pre">df_to_join</span></code>.</p>
<p>Data used in the example should be as compact as possible. The number of rows
is recommended to be around 4, but make it a number that makes sense for the
specific example. For example in the <code class="docutils literal notranslate"><span class="pre">head</span></code> method, it requires to be higher
than 5, to show the example with the default values. If doing the <code class="docutils literal notranslate"><span class="pre">mean</span></code>, we
could use something like <code class="docutils literal notranslate"><span class="pre">[1,</span> <span class="pre">2,</span> <span class="pre">3]</span></code>, so it is easy to see that the value
returned is the mean.</p>
<p>For more complex examples (groupping for example), avoid using data without
interpretation, like a matrix of random numbers with columns A, B, C, D…
And instead use a meaningful example, which makes it easier to understand the
concept. Unless required by the example, use names of animals, to keep examples
consistent. And numerical properties of them.</p>
<p>When calling the method, keywords arguments <code class="docutils literal notranslate"><span class="pre">head(n=3)</span></code> are preferred to
positional arguments <code class="docutils literal notranslate"><span class="pre">head(3)</span></code>.</p>
<p><strong>Good:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Series</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">mean</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Compute the mean of the input.</span>

<span class="sd">        Examples</span>
<span class="sd">        --------</span>
<span class="sd">        &gt;&gt;&gt; s = pd.Series([1, 2, 3])</span>
<span class="sd">        &gt;&gt;&gt; s.mean()</span>
<span class="sd">        2</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>


    <span class="k">def</span> <span class="nf">fillna</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Replace missing values by `value`.</span>

<span class="sd">        Examples</span>
<span class="sd">        --------</span>
<span class="sd">        &gt;&gt;&gt; s = pd.Series([1, np.nan, 3])</span>
<span class="sd">        &gt;&gt;&gt; s.fillna(0)</span>
<span class="sd">        [1, 0, 3]</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>

    <span class="k">def</span> <span class="nf">groupby_mean</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Group by index and return mean.</span>

<span class="sd">        Examples</span>
<span class="sd">        --------</span>
<span class="sd">        &gt;&gt;&gt; s = pd.Series([380., 370., 24., 26],</span>
<span class="sd">        ...               name=&#39;max_speed&#39;,</span>
<span class="sd">        ...               index=[&#39;falcon&#39;, &#39;falcon&#39;, &#39;parrot&#39;, &#39;parrot&#39;])</span>
<span class="sd">        &gt;&gt;&gt; s.groupby_mean()</span>
<span class="sd">        index</span>
<span class="sd">        falcon    375.0</span>
<span class="sd">        parrot     25.0</span>
<span class="sd">        Name: max_speed, dtype: float64</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>

    <span class="k">def</span> <span class="nf">contains</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pattern</span><span class="p">,</span> <span class="n">case_sensitive</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">na</span><span class="o">=</span><span class="n">numpy</span><span class="o">.</span><span class="n">nan</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Return whether each value contains `pattern`.</span>

<span class="sd">        In this case, we are illustrating how to use sections, even</span>
<span class="sd">        if the example is simple enough and does not require them.</span>

<span class="sd">        Examples</span>
<span class="sd">        --------</span>
<span class="sd">        &gt;&gt;&gt; s = pd.Series(&#39;Antelope&#39;, &#39;Lion&#39;, &#39;Zebra&#39;, numpy.nan)</span>
<span class="sd">        &gt;&gt;&gt; s.contains(pattern=&#39;a&#39;)</span>
<span class="sd">        0    False</span>
<span class="sd">        1    False</span>
<span class="sd">        2     True</span>
<span class="sd">        3      NaN</span>
<span class="sd">        dtype: bool</span>

<span class="sd">        **Case sensitivity**</span>

<span class="sd">        With `case_sensitive` set to `False` we can match `a` with both</span>
<span class="sd">        `a` and `A`:</span>

<span class="sd">        &gt;&gt;&gt; s.contains(pattern=&#39;a&#39;, case_sensitive=False)</span>
<span class="sd">        0     True</span>
<span class="sd">        1    False</span>
<span class="sd">        2     True</span>
<span class="sd">        3      NaN</span>
<span class="sd">        dtype: bool</span>

<span class="sd">        **Missing values**</span>

<span class="sd">        We can fill missing values in the output using the `na` parameter:</span>

<span class="sd">        &gt;&gt;&gt; s.contains(pattern=&#39;a&#39;, na=False)</span>
<span class="sd">        0    False</span>
<span class="sd">        1    False</span>
<span class="sd">        2     True</span>
<span class="sd">        3    False</span>
<span class="sd">        dtype: bool</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>
</pre></div>
</div>
<p><strong>Bad:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    A sample DataFrame method.</span>

<span class="sd">    Do not import numpy and pandas.</span>

<span class="sd">    Try to use meaningful data, when it makes the example easier</span>
<span class="sd">    to understand.</span>

<span class="sd">    Try to avoid positional arguments like in `df.method(1)`. They</span>
<span class="sd">    can be all right if previously defined with a meaningful name,</span>
<span class="sd">    like in `present_value(interest_rate)`, but avoid them otherwise.</span>

<span class="sd">    When presenting the behavior with different parameters, do not place</span>
<span class="sd">    all the calls one next to the other. Instead, add a short sentence</span>
<span class="sd">    explaining what the example shows.</span>

<span class="sd">    Examples</span>
<span class="sd">    --------</span>
<span class="sd">    &gt;&gt;&gt; import numpy as np</span>
<span class="sd">    &gt;&gt;&gt; import pandas as pd</span>
<span class="sd">    &gt;&gt;&gt; df = pd.DataFrame(numpy.random.randn(3, 3),</span>
<span class="sd">    ...                   columns=(&#39;a&#39;, &#39;b&#39;, &#39;c&#39;))</span>
<span class="sd">    &gt;&gt;&gt; df.method(1)</span>
<span class="sd">    21</span>
<span class="sd">    &gt;&gt;&gt; df.method(bar=14)</span>
<span class="sd">    123</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span>
</pre></div>
</div>
</div>
<div class="section" id="tips-for-getting-your-examples-pass-the-doctests">
<span id="docstring-doctest-tips"></span><h4>Tips for getting your examples pass the doctests<a class="headerlink" href="#tips-for-getting-your-examples-pass-the-doctests" title="Permalink to this headline">¶</a></h4>
<p>Getting the examples pass the doctests in the validation script can sometimes
be tricky. Here are some attention points:</p>
<ul>
<li><p class="first">Import all needed libraries (except for pandas and numpy, those are already
imported as <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">pandas</span> <span class="pre">as</span> <span class="pre">pd</span></code> and <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">numpy</span> <span class="pre">as</span> <span class="pre">np</span></code>) and define
all variables you use in the example.</p>
</li>
<li><p class="first">Try to avoid using random data. However random data might be OK in some
cases, like if the function you are documenting deals with probability
distributions, or if the amount of data needed to make the function result
meaningful is too much, such that creating it manually is very cumbersome.
In those cases, always use a fixed random seed to make the generated examples
predictable. Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">seed</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">df</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">({</span><span class="s1">&#39;normal&#39;</span><span class="p">:</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">normal</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">20</span><span class="p">)})</span>
</pre></div>
</div>
</li>
<li><p class="first">If you have a code snippet that wraps multiple lines, you need to use ‘…’
on the continued lines:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="p">[</span><span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">]],</span> <span class="n">index</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;a&#39;</span><span class="p">,</span> <span class="s1">&#39;b&#39;</span><span class="p">,</span> <span class="s1">&#39;c&#39;</span><span class="p">],</span>
<span class="gp">... </span>                  <span class="n">columns</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;A&#39;</span><span class="p">,</span> <span class="s1">&#39;B&#39;</span><span class="p">])</span>
</pre></div>
</div>
</li>
<li><p class="first">If you want to show a case where an exception is raised, you can do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">pd</span><span class="o">.</span><span class="n">to_datetime</span><span class="p">([</span><span class="s2">&quot;712-01-01&quot;</span><span class="p">])</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="gr">OutOfBoundsDatetime</span>: <span class="n">Out of bounds nanosecond timestamp: 712-01-01 00:00:00</span>
</pre></div>
</div>
<p>It is essential to include the “Traceback (most recent call last):”, but for
the actual error only the error name is sufficient.</p>
</li>
<li><p class="first">If there is a small part of the result that can vary (e.g. a hash in an object
represenation), you can use <code class="docutils literal notranslate"><span class="pre">...</span></code> to represent this part.</p>
<p>If you want to show that <code class="docutils literal notranslate"><span class="pre">s.plot()</span></code> returns a matplotlib AxesSubplot object,
this will fail the doctest</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">plot</span><span class="p">()</span>
<span class="go">&lt;matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690&gt;</span>
</pre></div>
</div>
<p>However, you can do (notice the comment that needs to be added)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">plot</span><span class="p">()</span>  
<span class="go">&lt;matplotlib.axes._subplots.AxesSubplot at ...&gt;</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="plots-in-examples">
<span id="docstring-example-plots"></span><h4>Plots in examples<a class="headerlink" href="#plots-in-examples" title="Permalink to this headline">¶</a></h4>
<p>There are some methods in pandas returning plots. To render the plots generated
by the examples in the documentation, the <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">plot::</span></code> directive exists.</p>
<p>To use it, place the next code after the “Examples” header as shown below. The
plot will be generated automatically when building the documentation.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Series</span><span class="p">:</span>
    <span class="k">def</span> <span class="nf">plot</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Generate a plot with the `Series` data.</span>

<span class="sd">        Examples</span>
<span class="sd">        --------</span>

<span class="sd">        .. plot::</span>
<span class="sd">            :context: close-figs</span>

<span class="sd">            &gt;&gt;&gt; s = pd.Series([1, 2, 3])</span>
<span class="sd">            &gt;&gt;&gt; s.plot()</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">pass</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/logo.png" alt="Logo"/>
            </a></p>
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">pandas docstring guide</a><ul>
<li><a class="reference internal" href="#about-docstrings-and-standards">About docstrings and standards</a></li>
<li><a class="reference internal" href="#writing-a-docstring">Writing a docstring</a><ul>
<li><a class="reference internal" href="#general-rules">General rules</a></li>
<li><a class="reference internal" href="#section-1-short-summary">Section 1: Short summary</a></li>
<li><a class="reference internal" href="#section-2-extended-summary">Section 2: Extended summary</a></li>
<li><a class="reference internal" href="#section-3-parameters">Section 3: Parameters</a><ul>
<li><a class="reference internal" href="#parameter-types">Parameter types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#section-4-returns-or-yields">Section 4: Returns or Yields</a></li>
<li><a class="reference internal" href="#section-5-see-also">Section 5: See Also</a></li>
<li><a class="reference internal" href="#section-6-notes">Section 6: Notes</a></li>
<li><a class="reference internal" href="#section-7-examples">Section 7: Examples</a><ul>
<li><a class="reference internal" href="#conventions-for-the-examples">Conventions for the examples</a></li>
<li><a class="reference internal" href="#tips-for-getting-your-examples-pass-the-doctests">Tips for getting your examples pass the doctests</a></li>
<li><a class="reference internal" href="#plots-in-examples">Plots in examples</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
      <li>Previous: <a href="pandas_setup.html" title="previous chapter">Before the sprint: Set up instructions</a></li>
      <li>Next: <a href="pandas_pr.html" title="next chapter">Submitting your changes</a></li>
  </ul></li>
</ul>
</div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/pandas_docstring.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.7.1</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
      
      |
      <a href="_sources/pandas_docstring.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    
  </body>
</html>