763 lines
50 KiB
HTML
763 lines
50 KiB
HTML
|
||
<!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 hasn’t 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 hasn’t 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> » </li>
|
||
<li><a href="../pep-0000/">PEP Index</a> » </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 <goodger at python.org></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 & 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 hasn’t 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 module’s 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 don’t 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 it’s 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 Corp’s 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 –>):</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">'is left as-is'</span>
|
||
<span class="n">spaces_and_linebreaks</span> <span class="o">=</span> <span class="s1">'are preserved'</span>
|
||
<span class="n">markup_processing</span> <span class="o">=</span> <span class="kc">None</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Doctest blocks begin with “>>> “ 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">'s a doctest block:</span>
|
||
|
||
<span class="o">>>></span> <span class="nb">print</span> <span class="s1">'Python-specific usage examples; begun with ">>>"'</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">">>>"</span>
|
||
<span class="o">>>></span> <span class="nb">print</span> <span class="s1">'(cut and pasted from interactive sessions)'</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">"""</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"> """</span>
|
||
|
||
<span class="n">instances</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="w"> </span><span class="sd">"""How many `Keeper` objects are there?"""</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">"""</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"> """</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">"""Store data in a list, most recent last."""</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">"""</span>
|
||
<span class="sd"> Extend `Storer.storedata()`; append new `data` to a</span>
|
||
<span class="sd"> list (in `self.data`).</span>
|
||
<span class="sd"> """</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'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, here’s 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 & 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 we’re talking about, and
|
||
docstrings shouldn’t 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? Isn’t 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, you’ll 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. Let’s 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? What’s 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">'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">"Bogus Complexity Addition"</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 & Footnotes
|
||
======================
|
||
|
||
.. _frungible doodads: http://www.example.org/
|
||
|
||
.. [#pep9876] PEP 9876, Let's Hope We Never Get Here
|
||
|
||
.. [#] "Bogus Complexity Addition"
|
||
</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 <a> 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 it’s 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">'s Hope We Never Get Here</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Footnotes are numbered, whereas citations use text for their
|
||
references.</p>
|
||
</li>
|
||
<li>Wouldn’t 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 & RFC references,
|
||
email masking, etc.).</p>
|
||
</li>
|
||
<li>Who’s 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>Won’t 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). Here’s 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. Python’s 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 & 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 & 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> |