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>
|