python-peps/pep-0287/index.html

763 lines
50 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="color-scheme" content="light dark">
<title>PEP 287 reStructuredText Docstring Format | peps.python.org</title>
<link rel="shortcut icon" href="../_static/py.png">
<link rel="canonical" href="https://peps.python.org/pep-0287/">
<link rel="stylesheet" href="../_static/style.css" type="text/css">
<link rel="stylesheet" href="../_static/mq.css" type="text/css">
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light">
<link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
<link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
<meta property="og:title" content='PEP 287 reStructuredText Docstring Format | peps.python.org'>
<meta property="og:description" content="When plaintext hasnt been expressive enough for inline documentation, Python programmers have sought out a format for docstrings. This PEP proposes that the reStructuredText markup be adopted as a standard markup format for structured plaintext docume...">
<meta property="og:type" content="website">
<meta property="og:url" content="https://peps.python.org/pep-0287/">
<meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
<meta property="og:image" content="https://peps.python.org/_static/og-image.png">
<meta property="og:image:alt" content="Python PEPs">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<meta name="description" content="When plaintext hasnt been expressive enough for inline documentation, Python programmers have sought out a format for docstrings. This PEP proposes that the reStructuredText markup be adopted as a standard markup format for structured plaintext docume...">
<meta name="theme-color" content="#3776ab">
</head>
<body>
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
<symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all">
<title>Following system colour scheme</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<circle cx="12" cy="12" r="9"></circle>
<path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path>
</svg>
</symbol>
<symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all">
<title>Selected dark colour scheme</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path stroke="none" d="M0 0h24v24H0z" fill="none"></path>
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path>
</svg>
</symbol>
<symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all">
<title>Selected light colour scheme</title>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<circle cx="12" cy="12" r="5"></circle>
<line x1="12" y1="1" x2="12" y2="3"></line>
<line x1="12" y1="21" x2="12" y2="23"></line>
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
<line x1="1" y1="12" x2="3" y2="12"></line>
<line x1="21" y1="12" x2="23" y2="12"></line>
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
</svg>
</symbol>
</svg>
<script>
document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto"
</script>
<section id="pep-page-section">
<header>
<h1>Python Enhancement Proposals</h1>
<ul class="breadcrumbs">
<li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> &raquo; </li>
<li><a href="../pep-0000/">PEP Index</a> &raquo; </li>
<li>PEP 287</li>
</ul>
<button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())">
<svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
<svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg>
<span class="visually-hidden">Toggle light / dark / auto colour theme</span>
</button>
</header>
<article>
<section id="pep-content">
<h1 class="page-title">PEP 287 reStructuredText Docstring Format</h1>
<dl class="rfc2822 field-list simple">
<dt class="field-odd">Author<span class="colon">:</span></dt>
<dd class="field-odd">David Goodger &lt;goodger&#32;&#97;t&#32;python.org&gt;</dd>
<dt class="field-even">Discussions-To<span class="colon">:</span></dt>
<dd class="field-even"><a class="reference external" href="https://mail.python.org/mailman/listinfo/doc-sig">Doc-SIG list</a></dd>
<dt class="field-odd">Status<span class="colon">:</span></dt>
<dd class="field-odd"><abbr title="Currently valid informational guidance, or an in-use process">Active</abbr></dd>
<dt class="field-even">Type<span class="colon">:</span></dt>
<dd class="field-even"><abbr title="Non-normative PEP containing background, guidelines or other information relevant to the Python ecosystem">Informational</abbr></dd>
<dt class="field-odd">Created<span class="colon">:</span></dt>
<dd class="field-odd">25-Mar-2002</dd>
<dt class="field-even">Post-History<span class="colon">:</span></dt>
<dd class="field-even">02-Apr-2002</dd>
<dt class="field-odd">Replaces<span class="colon">:</span></dt>
<dd class="field-odd"><a class="reference external" href="../pep-0216/">216</a></dd>
</dl>
<hr class="docutils" />
<section id="contents">
<details><summary>Table of Contents</summary><ul class="simple">
<li><a class="reference internal" href="#abstract">Abstract</a></li>
<li><a class="reference internal" href="#benefits">Benefits</a></li>
<li><a class="reference internal" href="#goals">Goals</a></li>
<li><a class="reference internal" href="#rationale">Rationale</a></li>
<li><a class="reference internal" href="#specification">Specification</a></li>
<li><a class="reference internal" href="#docstring-significant-features">Docstring-Significant Features</a></li>
<li><a class="reference internal" href="#questions-answers">Questions &amp; Answers</a></li>
<li><a class="reference internal" href="#copyright">Copyright</a></li>
<li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li>
</ul>
</details></section>
<section id="abstract">
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
<p>When plaintext hasnt been expressive enough for inline documentation,
Python programmers have sought out a format for docstrings. This PEP
proposes that the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText markup</a> be adopted as a standard
markup format for structured plaintext documentation in Python
docstrings, and for PEPs and ancillary documents as well.
reStructuredText is a rich and extensible yet easy-to-read,
what-you-see-is-what-you-get plaintext markup syntax.</p>
<p>Only the low-level syntax of docstrings is addressed here. This PEP
is not concerned with docstring semantics or processing at all (see
<a class="pep reference internal" href="../pep-0256/" title="PEP 256 Docstring Processing System Framework">PEP 256</a> for a “Road Map to the Docstring PEPs”). Nor is it an attempt
to deprecate pure plaintext docstrings, which are always going to be
legitimate. The reStructuredText markup is an alternative for those
who want more expressive docstrings.</p>
</section>
<section id="benefits">
<h2><a class="toc-backref" href="#benefits" role="doc-backlink">Benefits</a></h2>
<p>Programmers are by nature a lazy breed. We reuse code with functions,
classes, modules, and subsystems. Through its docstring syntax,
Python allows us to document our code from within. The “holy grail”
of the Python Documentation Special Interest Group (<a class="reference external" href="http://www.python.org/sigs/doc-sig/">Doc-SIG</a>) has been
a markup syntax and toolset to allow auto-documentation, where the
docstrings of Python systems can be extracted in context and processed
into useful, high-quality documentation for multiple purposes.</p>
<p>Document markup languages have three groups of customers: the authors
who write the documents, the software systems that process the data,
and the readers, who are the final consumers and the most important
group. Most markups are designed for the authors and software
systems; readers are only meant to see the processed form, either on
paper or via browser software. ReStructuredText is different: it is
intended to be easily readable in source form, without prior knowledge
of the markup. ReStructuredText is entirely readable in plaintext
format, and many of the markup forms match common usage (e.g.,
<code class="docutils literal notranslate"><span class="pre">*emphasis*</span></code>), so it reads quite naturally. Yet it is rich enough
to produce complex documents, and extensible so that there are few
limits. Of course, to write reStructuredText documents some prior
knowledge is required.</p>
<p>The markup offers functionality and expressivity, while maintaining
easy readability in the source text. The processed form (HTML etc.)
makes it all accessible to readers: inline live hyperlinks; live links
to and from footnotes; automatic tables of contents (with live
links!); tables; images for diagrams etc.; pleasant, readable styled
text.</p>
<p>The reStructuredText parser is available now, part of the <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a>
project. Standalone reStructuredText documents and PEPs can be
converted to HTML; other output format writers are being worked on and
will become available over time. Work is progressing on a Python
source “Reader” which will implement auto-documentation from
docstrings. Authors of existing auto-documentation tools are
encouraged to integrate the reStructuredText parser into their
projects, or better yet, to join forces to produce a world-class
toolset for the Python standard library.</p>
<p>Tools will become available in the near future, which will allow
programmers to generate HTML for online help, XML for multiple
purposes, and eventually PDF, DocBook, and LaTeX for printed
documentation, essentially “for free” from the existing docstrings.
The adoption of a standard will, at the very least, benefit docstring
processing tools by preventing further “reinventing the wheel”.</p>
<p>Eventually PyDoc, the one existing standard auto-documentation tool,
could have reStructuredText support added. In the interim it will
have no problem with reStructuredText markup, since it treats all
docstrings as preformatted plaintext.</p>
</section>
<section id="goals">
<h2><a class="toc-backref" href="#goals" role="doc-backlink">Goals</a></h2>
<p>These are the generally accepted goals for a docstring format, as
discussed in the Doc-SIG:</p>
<ol class="arabic simple">
<li>It must be readable in source form by the casual observer.</li>
<li>It must be easy to type with any standard text editor.</li>
<li>It must not need to contain information which can be deduced from
parsing the module.</li>
<li>It must contain sufficient information (structure) so it can be
converted to any reasonable markup format.</li>
<li>It must be possible to write a modules entire documentation in
docstrings, without feeling hampered by the markup language.</li>
</ol>
<p>reStructuredText meets and exceeds all of these goals, and sets its
own goals as well, even more stringent. See <a class="reference internal" href="#docstring-significant-features">Docstring-Significant
Features</a> below.</p>
<p>The goals of this PEP are as follows:</p>
<ol class="arabic">
<li>To establish reStructuredText as a standard structured plaintext
format for docstrings (inline documentation of Python modules and
packages), PEPs, README-type files and other standalone documents.
“Accepted” status will be sought through Python community consensus
and eventual BDFL pronouncement.<p>Please note that reStructuredText is being proposed as <em>a</em>
standard, not <em>the only</em> standard. Its use will be entirely
optional. Those who dont want to use it need not.</p>
</li>
<li>To solicit and address any related concerns raised by the Python
community.</li>
<li>To encourage community support. As long as multiple competing
markups are out there, the development community remains fractured.
Once a standard exists, people will start to use it, and momentum
will inevitably gather.</li>
<li>To consolidate efforts from related auto-documentation projects.
It is hoped that interested developers will join forces and work on
a joint/merged/common implementation.</li>
</ol>
<p>Once reStructuredText is a Python standard, effort can be focused on
tools instead of arguing for a standard. Python needs a standard set
of documentation tools.</p>
<p>With regard to PEPs, one or both of the following strategies may be
applied:</p>
<ol class="loweralpha simple">
<li>Keep the existing PEP section structure constructs (one-line
section headers, indented body text). Subsections can either be
forbidden, or supported with reStructuredText-style underlined
headers in the indented body text.</li>
<li>Replace the PEP section structure constructs with the
reStructuredText syntax. Section headers will require underlines,
subsections will be supported out of the box, and body text need
not be indented (except for block quotes).</li>
</ol>
<p>Strategy (b) is recommended, and its implementation is complete.</p>
<p>Support for <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a> headers has been added to the reStructuredText
parser for PEPs (unambiguous given a specific context: the first
contiguous block of the document). It may be desired to concretely
specify what over/underline styles are allowed for PEP section
headers, for uniformity.</p>
</section>
<section id="rationale">
<h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2>
<p>The lack of a standard syntax for docstrings has hampered the
development of standard tools for extracting and converting docstrings
into documentation in standard formats (e.g., HTML, DocBook, TeX).
There have been a number of proposed markup formats and variations,
and many tools tied to these proposals, but without a standard
docstring format they have failed to gain a strong following and/or
floundered half-finished.</p>
<p>Throughout the existence of the Doc-SIG, consensus on a single
standard docstring format has never been reached. A lightweight,
implicit markup has been sought, for the following reasons (among
others):</p>
<ol class="arabic simple">
<li>Docstrings written within Python code are available from within the
interactive interpreter, and can be “print”ed. Thus the use of
plaintext for easy readability.</li>
<li>Programmers want to add structure to their docstrings, without
sacrificing raw docstring readability. Unadorned plaintext cannot
be transformed (“up-translated”) into useful structured formats.</li>
<li>Explicit markup (like XML or TeX) is widely considered unreadable
by the uninitiated.</li>
<li>Implicit markup is aesthetically compatible with the clean and
minimalist Python syntax.</li>
</ol>
<p>Many alternative markups for docstrings have been proposed on the
Doc-SIG over the years; a representative sample is listed below. Each
is briefly analyzed in terms of the goals stated above. Please note
that this is <em>not</em> intended to be an exclusive list of all existing
markup systems; there are many other markups (Texinfo, Doxygen, TIM,
YODL, AFT, …) which are not mentioned.</p>
<ul>
<li><a class="reference external" href="http://www.w3.org/XML/">XML</a>, <a class="reference external" href="http://www.oasis-open.org/cover/general.html">SGML</a>, <a class="reference external" href="http://docbook.org/tdg/en/html/docbook.html">DocBook</a>, <a class="reference external" href="http://www.w3.org/MarkUp/">HTML</a>, <a class="reference external" href="http://www.w3.org/MarkUp/#xhtml1">XHTML</a><p>XML and SGML are explicit, well-formed meta-languages suitable for
all kinds of documentation. XML is a variant of SGML. They are
best used behind the scenes, because to untrained eyes they are
verbose, difficult to type, and too cluttered to read comfortably as
source. DocBook, HTML, and XHTML are all applications of SGML
and/or XML, and all share the same basic syntax and the same
shortcomings.</p>
</li>
<li><a class="reference external" href="http://www.tug.org/interest.html">TeX</a><p>TeX is similar to XML/SGML in that its explicit, but not very easy
to write, and not easy for the uninitiated to read.</p>
</li>
<li><a class="reference external" href="http://perldoc.perl.org/perlpod.html">Perl POD</a><p>Most Perl modules are documented in a format called POD (Plain Old
Documentation). This is an easy-to-type, very low level format with
strong integration with the Perl parser. Many tools exist to turn
POD documentation into other formats: info, HTML and man pages,
among others. However, the POD syntax takes after Perl itself in
terms of readability.</p>
</li>
<li><a class="reference external" href="http://java.sun.com/j2se/javadoc/">JavaDoc</a><p>Special comments before Java classes and functions serve to document
the code. A program to extract these, and turn them into HTML
documentation is called javadoc, and is part of the standard Java
distribution. However, JavaDoc has a very intimate relationship
with HTML, using HTML tags for most markup. Thus it shares the
readability problems of HTML.</p>
</li>
<li><a class="reference external" href="http://docutils.sourceforge.net/mirror/setext.html">Setext</a>, <a class="reference external" href="http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage">StructuredText</a><p>Early on, variants of Setext (Structure Enhanced Text), including
Zope Corps StructuredText, were proposed for Python docstring
formatting. Hereafter these variants will collectively be called
“STexts”. STexts have the advantage of being easy to read without
special knowledge, and relatively easy to write.</p>
<p>Although used by some (including in most existing Python
auto-documentation tools), until now STexts have failed to become
standard because:</p>
<ul class="simple">
<li>STexts have been incomplete. Lacking “essential” constructs that
people want to use in their docstrings, STexts are rendered less
than ideal. Note that these “essential” constructs are not
universal; everyone has their own requirements.</li>
<li>STexts have been sometimes surprising. Bits of text are
unexpectedly interpreted as being marked up, leading to user
frustration.</li>
<li>SText implementations have been buggy.</li>
<li>Most STexts have no formal specification except for the
implementation itself. A buggy implementation meant a buggy spec,
and vice-versa.</li>
<li>There has been no mechanism to get around the SText markup rules
when a markup character is used in a non-markup context. In other
words, no way to escape markup.</li>
</ul>
</li>
</ul>
<p>Proponents of implicit STexts have vigorously opposed proposals for
explicit markup (XML, HTML, TeX, POD, etc.), and the debates have
continued off and on since 1996 or earlier.</p>
<p>reStructuredText is a complete revision and reinterpretation of the
SText idea, addressing all of the problems listed above.</p>
</section>
<section id="specification">
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
<p>The specification and user documentation for reStructuredText is
quite extensive. Rather than repeating or summarizing it all
here, links to the originals are provided.</p>
<p>Please first take a look at <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickstart.html">A ReStructuredText Primer</a>, a short and
gentle introduction. The <a class="reference external" href="http://docutils.sourceforge.net/docs/user/rst/quickref.html">Quick reStructuredText</a> user reference
quickly summarizes all of the markup constructs. For complete and
extensive details, please refer to the following documents:</p>
<ul class="simple">
<li><a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/introduction.html">An Introduction to reStructuredText</a></li>
<li><a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">reStructuredText Markup Specification</a></li>
<li><a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html">reStructuredText Directives</a></li>
</ul>
<p>In addition, <a class="reference external" href="http://docutils.sourceforge.net/docs/dev/rst/problems.html">Problems With StructuredText</a> explains many markup
decisions made with regards to StructuredText, and <a class="reference external" href="http://docutils.sourceforge.net/docs/dev/rst/alternatives.html">A Record of
reStructuredText Syntax Alternatives</a> records markup decisions made
independently.</p>
</section>
<section id="docstring-significant-features">
<h2><a class="toc-backref" href="#docstring-significant-features" role="doc-backlink">Docstring-Significant Features</a></h2>
<ul>
<li>A markup escaping mechanism.<p>Backslashes (<code class="docutils literal notranslate"><span class="pre">\</span></code>) are used to escape markup characters when needed
for non-markup purposes. However, the inline markup recognition
rules have been constructed in order to minimize the need for
backslash-escapes. For example, although asterisks are used for
<em>emphasis</em>, in non-markup contexts such as “*” or “(*)” or “x * y”,
the asterisks are not interpreted as markup and are left unchanged.
For many non-markup uses of backslashes (e.g., describing regular
expressions), inline literals or literal blocks are applicable; see
the next item.</p>
</li>
<li>Markup to include Python source code and Python interactive
sessions: inline literals, literal blocks, and doctest blocks.<p>Inline literals use <code class="docutils literal notranslate"><span class="pre">double-backquotes</span></code> to indicate program I/O or
code snippets. No markup interpretation (including backslash-escape
[<code class="docutils literal notranslate"><span class="pre">\</span></code>] interpretation) is done within inline literals.</p>
<p>Literal blocks (block-level literal text, such as code excerpts or
ASCII graphics) are indented, and indicated with a double-colon
(“::”) at the end of the preceding paragraph (right here &gt;):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">literal_block</span><span class="p">:</span>
<span class="n">text</span> <span class="o">=</span> <span class="s1">&#39;is left as-is&#39;</span>
<span class="n">spaces_and_linebreaks</span> <span class="o">=</span> <span class="s1">&#39;are preserved&#39;</span>
<span class="n">markup_processing</span> <span class="o">=</span> <span class="kc">None</span>
</pre></div>
</div>
<p>Doctest blocks begin with “&gt;&gt;&gt; “ and end with a blank line. Neither
indentation nor literal block double-colons are required. For
example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Here</span><span class="s1">&#39;s a doctest block:</span>
<span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span> <span class="s1">&#39;Python-specific usage examples; begun with &quot;&gt;&gt;&gt;&quot;&#39;</span>
<span class="n">Python</span><span class="o">-</span><span class="n">specific</span> <span class="n">usage</span> <span class="n">examples</span><span class="p">;</span> <span class="n">begun</span> <span class="k">with</span> <span class="s2">&quot;&gt;&gt;&gt;&quot;</span>
<span class="o">&gt;&gt;&gt;</span> <span class="nb">print</span> <span class="s1">&#39;(cut and pasted from interactive sessions)&#39;</span>
<span class="p">(</span><span class="n">cut</span> <span class="ow">and</span> <span class="n">pasted</span> <span class="kn">from</span> <span class="nn">interactive</span> <span class="n">sessions</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li>Markup that isolates a Python identifier: interpreted text.<p>Text enclosed in single backquotes is recognized as “interpreted
text”, whose interpretation is application-dependent. In the
context of a Python docstring, the default interpretation of
interpreted text is as Python identifiers. The text will be marked
up with a hyperlink connected to the documentation for the
identifier given. Lookup rules are the same as in Python itself:
LGB namespace lookups (local, global, builtin). The “role” of the
interpreted text (identifying a class, module, function, etc.) is
determined implicitly from the namespace lookup. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Keeper</span><span class="p">(</span><span class="n">Storer</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Keep data fresher longer.</span>
<span class="sd"> Extend `Storer`. Class attribute `instances` keeps track</span>
<span class="sd"> of the number of `Keeper` objects instantiated.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">instances</span> <span class="o">=</span> <span class="mi">0</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;How many `Keeper` objects are there?&quot;&quot;&quot;</span>
<span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Extend `Storer.__init__()` to keep track of</span>
<span class="sd"> instances. Keep count in `self.instances` and data</span>
<span class="sd"> in `self.data`.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">Storer</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">instances</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="bp">self</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="p">[]</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;Store data in a list, most recent last.&quot;&quot;&quot;</span>
<span class="k">def</span> <span class="nf">storedata</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="w"> </span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Extend `Storer.storedata()`; append new `data` to a</span>
<span class="sd"> list (in `self.data`).</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="bp">self</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="n">data</span>
</pre></div>
</div>
<p>Each piece of interpreted text is looked up according to the local
namespace of the block containing its docstring.</p>
</li>
<li>Markup that isolates a Python identifier and specifies its type:
interpreted text with roles.<p>Although the Python source context reader is designed not to require
explicit roles, they may be used. To classify identifiers
explicitly, the role is given along with the identifier in either
prefix or suffix form:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Use :method:`Keeper.storedata` to store the object&#39;s data in
`Keeper.data`:instance_attribute:.
</pre></div>
</div>
<p>The syntax chosen for roles is verbose, but necessarily so (if
anyone has a better alternative, please post it to the <a class="reference external" href="http://www.python.org/sigs/doc-sig/">Doc-SIG</a>).
The intention of the markup is that there should be little need to
use explicit roles; their use is to be kept to an absolute minimum.</p>
</li>
<li>Markup for “tagged lists” or “label lists”: field lists.<p>Field lists represent a mapping from field name to field body.
These are mostly used for extension syntax, such as “bibliographic
field lists” (representing document metadata such as author, date,
and version) and extension attributes for directives (see below).
They may be used to implement methodologies (docstring semantics),
such as identifying parameters, exceptions raised, etc.; such usage
is beyond the scope of this PEP.</p>
<p>A modified <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a> syntax is used, with a colon <em>before</em> as well as
<em>after</em> the field name. Field bodies are more versatile as well;
they may contain multiple field bodies (even nested field lists).
For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">:</span><span class="n">Date</span><span class="p">:</span> <span class="mi">2002</span><span class="o">-</span><span class="mi">03</span><span class="o">-</span><span class="mi">22</span>
<span class="p">:</span><span class="n">Version</span><span class="p">:</span> <span class="mi">1</span>
<span class="p">:</span><span class="n">Authors</span><span class="p">:</span>
<span class="o">-</span> <span class="n">Me</span>
<span class="o">-</span> <span class="n">Myself</span>
<span class="o">-</span> <span class="n">I</span>
</pre></div>
</div>
<p>Standard <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2822.html"><strong>RFC 2822</strong></a> header syntax cannot be used for this construct
because it is ambiguous. A word followed by a colon at the
beginning of a line is common in written text.</p>
</li>
<li>Markup extensibility: directives and substitutions.<p>Directives are used as an extension mechanism for reStructuredText,
a way of adding support for new block-level constructs without
adding new syntax. Directives for images, admonitions (note,
caution, etc.), and tables of contents generation (among others)
have been implemented. For example, heres how to place an image:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">image</span><span class="p">::</span> <span class="n">mylogo</span><span class="o">.</span><span class="n">png</span>
</pre></div>
</div>
<p>Substitution definitions allow the power and flexibility of
block-level directives to be shared by inline text. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">The</span> <span class="o">|</span><span class="n">biohazard</span><span class="o">|</span> <span class="n">symbol</span> <span class="n">must</span> <span class="n">be</span> <span class="n">used</span> <span class="n">on</span> <span class="n">containers</span> <span class="n">used</span> <span class="n">to</span>
<span class="n">dispose</span> <span class="n">of</span> <span class="n">medical</span> <span class="n">waste</span><span class="o">.</span>
<span class="o">..</span> <span class="o">|</span><span class="n">biohazard</span><span class="o">|</span> <span class="n">image</span><span class="p">::</span> <span class="n">biohazard</span><span class="o">.</span><span class="n">png</span>
</pre></div>
</div>
</li>
<li>Section structure markup.<p>Section headers in reStructuredText use adornment via underlines
(and possibly overlines) rather than indentation. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">Section</span> <span class="n">Title</span>
<span class="o">=======================</span>
<span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">Subsection</span> <span class="n">Title</span>
<span class="o">--------------------------</span>
<span class="n">This</span> <span class="n">paragraph</span> <span class="ow">is</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">subsection</span><span class="o">.</span>
<span class="n">This</span> <span class="ow">is</span> <span class="n">Another</span> <span class="n">Section</span> <span class="n">Title</span>
<span class="o">=============================</span>
<span class="n">This</span> <span class="n">paragraph</span> <span class="ow">is</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">second</span> <span class="n">section</span><span class="o">.</span>
</pre></div>
</div>
</li>
</ul>
</section>
<section id="questions-answers">
<h2><a class="toc-backref" href="#questions-answers" role="doc-backlink">Questions &amp; Answers</a></h2>
<ol class="arabic">
<li>Is reStructuredText rich enough?<p>Yes, it is for most people. If it lacks some construct that is
required for a specific application, it can be added via the
directive mechanism. If a useful and common construct has been
overlooked and a suitably readable syntax can be found, it can be
added to the specification and parser.</p>
</li>
<li>Is reStructuredText <em>too</em> rich?<p>For specific applications or individuals, perhaps. In general, no.</p>
<p>Since the very beginning, whenever a docstring markup syntax has
been proposed on the <a class="reference external" href="http://www.python.org/sigs/doc-sig/">Doc-SIG</a>, someone has complained about the
lack of support for some construct or other. The reply was often
something like, “These are docstrings were talking about, and
docstrings shouldnt have complex markup.” The problem is that a
construct that seems superfluous to one person may be absolutely
essential to another.</p>
<p>reStructuredText takes the opposite approach: it provides a rich
set of implicit markup constructs (plus a generic extension
mechanism for explicit markup), allowing for all kinds of
documents. If the set of constructs is too rich for a particular
application, the unused constructs can either be removed from the
parser (via application-specific overrides) or simply omitted by
convention.</p>
</li>
<li>Why not use indentation for section structure, like StructuredText
does? Isnt it more “Pythonic”?<p>Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post:</p>
<blockquote>
<div>I still think that using indentation to indicate sectioning is
wrong. If you look at how real books and other print
publications are laid out, youll notice that indentation is
used frequently, but mostly at the intra-section level.
Indentation can be used to offset lists, tables, quotations,
examples, and the like. (The argument that docstrings are
different because they are input for a text formatter is wrong:
the whole point is that they are also readable without
processing.)<p>I reject the argument that using indentation is Pythonic: text
is not code, and different traditions and conventions hold.
People have been presenting text for readability for over 30
centuries. Lets not innovate needlessly.</p>
</div></blockquote>
<p>See <a class="reference external" href="http://docutils.sourceforge.net/docs/dev/rst/problems.html#section-structure-via-indentation">Section Structure via Indentation</a> in <a class="reference external" href="http://docutils.sourceforge.net/docs/dev/rst/problems.html">Problems With
StructuredText</a> for further elaboration.</p>
</li>
<li>Why use reStructuredText for PEPs? Whats wrong with the existing
standard?<p>The existing standard for PEPs is very limited in terms of general
expressibility, and referencing is especially lacking for such a
reference-rich document type. PEPs are currently converted into
HTML, but the results (mostly monospaced text) are less than
attractive, and most of the value-added potential of HTML
(especially inline hyperlinks) is untapped.</p>
<p>Making reStructuredText a standard markup for PEPs will enable much
richer expression, including support for section structure, inline
markup, graphics, and tables. In several PEPs there are ASCII
graphics diagrams, which are all that plaintext documents can
support. Since PEPs are made available in HTML form, the ability
to include proper diagrams would be immediately useful.</p>
<p>Current PEP practices allow for reference markers in the form “[1]”
in the text, and the footnotes/references themselves are listed in
a section toward the end of the document. There is currently no
hyperlinking between the reference marker and the
footnote/reference itself (it would be possible to add this to
pep2html.py, but the “markup” as it stands is ambiguous and
mistakes would be inevitable). A PEP with many references (such as
this one ;-) requires a lot of flipping back and forth. When
revising a PEP, often new references are added or unused references
deleted. It is painful to renumber the references, since it has to
be done in two places and can have a cascading effect (insert a
single new reference 1, and every other reference has to be
renumbered; always adding new references to the end is suboptimal).
It is easy for references to go out of sync.</p>
<p>PEPs use references for two purposes: simple URL references and
footnotes. reStructuredText differentiates between the two. A PEP
might contain references like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Abstract</span>
<span class="n">This</span> <span class="n">PEP</span> <span class="n">proposes</span> <span class="n">adding</span> <span class="n">frungible</span> <span class="n">doodads</span> <span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="n">to</span> <span class="n">the</span> <span class="n">core</span><span class="o">.</span>
<span class="n">It</span> <span class="n">extends</span> <span class="n">PEP</span> <span class="mi">9876</span> <span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="n">via</span> <span class="n">the</span> <span class="n">BCA</span> <span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="n">mechanism</span><span class="o">.</span>
<span class="o">...</span>
<span class="n">References</span> <span class="ow">and</span> <span class="n">Footnotes</span>
<span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">org</span><span class="o">/</span>
<span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="n">PEP</span> <span class="mi">9876</span><span class="p">,</span> <span class="n">Let</span><span class="s1">&#39;s Hope We Never Get Here</span>
<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">peps</span><span class="o">.</span><span class="n">python</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">pep</span><span class="o">-</span><span class="mi">9876</span><span class="o">/</span>
<span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="s2">&quot;Bogus Complexity Addition&quot;</span>
</pre></div>
</div>
<p>Reference 1 is a simple URL reference. Reference 2 is a footnote
containing text and a URL. Reference 3 is a footnote containing
text only. Rewritten using reStructuredText, this PEP could look
like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Abstract
========
This PEP proposes adding `frungible doodads`_ to the core. It
extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.
...
References &amp; Footnotes
======================
.. _frungible doodads: http://www.example.org/
.. [#pep9876] PEP 9876, Let&#39;s Hope We Never Get Here
.. [#] &quot;Bogus Complexity Addition&quot;
</pre></div>
</div>
<p>URLs and footnotes can be defined close to their references if
desired, making them easier to read in the source text, and making
the PEPs easier to revise. The “References and Footnotes” section
can be auto-generated with a document tree transform. Footnotes
from throughout the PEP would be gathered and displayed under a
standard header. If URL references should likewise be written out
explicitly (in citation form), another tree transform could be
used.</p>
<p>URL references can be named (“frungible doodads”), and can be
referenced from multiple places in the document without additional
definitions. When converted to HTML, references will be replaced
with inline hyperlinks (HTML &lt;a&gt; tags). The two footnotes are
automatically numbered, so they will always stay in sync. The
first footnote also contains an internal reference name, “pep9876”,
so its easier to see the connection between reference and footnote
in the source text. Named footnotes can be referenced multiple
times, maintaining consistent numbering.</p>
<p>The “#pep9876” footnote could also be written in the form of a
citation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">It</span> <span class="n">extends</span> <span class="n">PEP</span> <span class="mi">9876</span> <span class="p">[</span><span class="n">PEP9876</span><span class="p">]</span><span class="n">_</span> <span class="o">...</span>
<span class="o">..</span> <span class="p">[</span><span class="n">PEP9876</span><span class="p">]</span> <span class="n">PEP</span> <span class="mi">9876</span><span class="p">,</span> <span class="n">Let</span><span class="s1">&#39;s Hope We Never Get Here</span>
</pre></div>
</div>
<p>Footnotes are numbered, whereas citations use text for their
references.</p>
</li>
<li>Wouldnt it be better to keep the docstring and PEP proposals
separate?<p>The PEP markup proposal may be removed if it is deemed that there
is no need for PEP markup, or it could be made into a separate PEP.
If accepted, <a class="pep reference internal" href="../pep-0001/" title="PEP 1 PEP Purpose and Guidelines">PEP 1</a>, PEP Purpose and Guidelines, and <a class="pep reference internal" href="../pep-0009/" title="PEP 9 Sample Plaintext PEP Template">PEP 9</a>,
Sample PEP Template will be updated.</p>
<p>It seems natural to adopt a single consistent markup standard for
all uses of structured plaintext in Python, and to propose it all
in one place.</p>
</li>
<li>The existing pep2html.py script converts the existing PEP format to
HTML. How will the new-format PEPs be converted to HTML?<p>A new version of pep2html.py with integrated reStructuredText
parsing has been completed. The Docutils project supports PEPs
with a “PEP Reader” component, including all functionality
currently in pep2html.py (auto-recognition of PEP &amp; RFC references,
email masking, etc.).</p>
</li>
<li>Whos going to convert the existing PEPs to reStructuredText?<p>PEP authors or volunteers may convert existing PEPs if they like,
but there is no requirement to do so. The reStructuredText-based
PEPs will coexist with the old PEP standard. The pep2html.py
mentioned in answer 6 processes both old and new standards.</p>
</li>
<li>Why use reStructuredText for README and other ancillary files?<p>The reasoning given for PEPs in answer 4 above also applies to
README and other ancillary files. By adopting a standard markup,
these files can be converted to attractive cross-referenced HTML
and put up on python.org. Developers of other projects can also
take advantage of this facility for their own documentation.</p>
</li>
<li>Wont the superficial similarity to existing markup conventions
cause problems, and result in people writing invalid markup (and
not noticing, because the plaintext looks natural)? How forgiving
is reStructuredText of “not quite right” markup?<p>There will be some mis-steps, as there would be when moving from
one programming language to another. As with any language,
proficiency grows with experience. Luckily, reStructuredText is a
very little language indeed.</p>
<p>As with any syntax, there is the possibility of syntax errors. It
is expected that a user will run the processing system over their
input and check the output for correctness.</p>
<p>In a strict sense, the reStructuredText parser is very unforgiving
(as it should be; <a class="pep reference internal" href="../pep-0020/" title="PEP 20 The Zen of Python">“In the face of ambiguity, refuse the temptation
to guess”</a> applies to parsing markup as well as computer
languages). Heres design goal 3 from <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/introduction.html">An Introduction to
reStructuredText</a>:</p>
<blockquote>
<div>Unambiguous. The rules for markup must not be open for
interpretation. For any given input, there should be one and
only one possible output (including error output).</div></blockquote>
<p>While unforgiving, at the same time the parser does try to be
helpful by producing useful diagnostic output (“system messages”).
The parser reports problems, indicating their level of severity
(from least to most: debug, info, warning, error, severe). The
user or the client software can decide on reporting thresholds;
they can ignore low-level problems or cause high-level problems to
bring processing to an immediate halt. Problems are reported
during the parse as well as included in the output, often with
two-way links between the source of the problem and the system
message explaining it.</p>
</li>
<li>Will the docstrings in the Python standard library modules be
converted to reStructuredText?<p>No. Pythons library reference documentation is maintained
separately from the source. Docstrings in the Python standard
library should not try to duplicate the library reference
documentation. The current policy for docstrings in the Python
standard library is that they should be no more than concise
hints, simple and markup-free (although many <em>do</em> contain ad-hoc
implicit markup).</p>
</li>
<li>I want to write all my strings in Unicode. Will anything
break?<p>The parser fully supports Unicode. Docutils supports arbitrary
input and output encodings.</p>
</li>
<li>Why does the community need a new structured text design?<p>The existing structured text designs are deficient, for the
reasons given in “Rationale” above. reStructuredText aims to be a
complete markup syntax, within the limitations of the “readable
plaintext” medium.</p>
</li>
<li>What is wrong with existing documentation methodologies?<p>What existing methodologies? For Python docstrings, there is
<strong>no</strong> official standard markup format, let alone a documentation
methodology akin to JavaDoc. The question of methodology is at a
much higher level than syntax (which this PEP addresses). It is
potentially much more controversial and difficult to resolve, and
is intentionally left out of this discussion.</p>
</li>
</ol>
</section>
<section id="copyright">
<h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2>
<p>This document has been placed in the public domain.</p>
</section>
<section id="acknowledgements">
<h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2>
<p>Some text is borrowed from <a class="pep reference internal" href="../pep-0216/" title="PEP 216 Docstring Format">PEP 216</a>, Docstring Format, by
Moshe Zadka.</p>
<p>Special thanks to all members past &amp; present of the Python <a class="reference external" href="http://www.python.org/sigs/doc-sig/">Doc-SIG</a>.</p>
</section>
</section>
<hr class="docutils" />
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0287.rst">https://github.com/python/peps/blob/main/peps/pep-0287.rst</a></p>
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0287.rst">2023-09-09 17:39:29 GMT</a></p>
</article>
<nav id="pep-sidebar">
<h2>Contents</h2>
<ul>
<li><a class="reference internal" href="#abstract">Abstract</a></li>
<li><a class="reference internal" href="#benefits">Benefits</a></li>
<li><a class="reference internal" href="#goals">Goals</a></li>
<li><a class="reference internal" href="#rationale">Rationale</a></li>
<li><a class="reference internal" href="#specification">Specification</a></li>
<li><a class="reference internal" href="#docstring-significant-features">Docstring-Significant Features</a></li>
<li><a class="reference internal" href="#questions-answers">Questions &amp; Answers</a></li>
<li><a class="reference internal" href="#copyright">Copyright</a></li>
<li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li>
</ul>
<br>
<a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0287.rst">Page Source (GitHub)</a>
</nav>
</section>
<script src="../_static/colour_scheme.js"></script>
<script src="../_static/wrap_tables.js"></script>
<script src="../_static/sticky_banner.js"></script>
</body>
</html>