mirror of https://github.com/python/peps
979 lines
63 KiB
HTML
979 lines
63 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 258 – Docutils Design Specification | peps.python.org</title>
|
||
<link rel="shortcut icon" href="../_static/py.png">
|
||
<link rel="canonical" href="https://peps.python.org/pep-0258/">
|
||
<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 258 – Docutils Design Specification | peps.python.org'>
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:url" content="https://peps.python.org/pep-0258/">
|
||
<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="Python Enhancement Proposals (PEPs)">
|
||
<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 258</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 258 – Docutils Design Specification</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="Formally declined and will not be accepted">Rejected</abbr></dd>
|
||
<dt class="field-even">Type<span class="colon">:</span></dt>
|
||
<dd class="field-even"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd>
|
||
<dt class="field-odd">Requires<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><a class="reference external" href="../pep-0256/">256</a>, <a class="reference external" href="../pep-0257/">257</a></dd>
|
||
<dt class="field-even">Created<span class="colon">:</span></dt>
|
||
<dd class="field-even">31-May-2001</dd>
|
||
<dt class="field-odd">Post-History<span class="colon">:</span></dt>
|
||
<dd class="field-odd">13-Jun-2001</dd>
|
||
</dl>
|
||
<hr class="docutils" />
|
||
<section id="contents">
|
||
<details><summary>Table of Contents</summary><ul class="simple">
|
||
<li><a class="reference internal" href="#rejection-notice">Rejection Notice</a></li>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#docutils-project-model">Docutils Project Model</a><ul>
|
||
<li><a class="reference internal" href="#publisher">Publisher</a></li>
|
||
<li><a class="reference internal" href="#readers">Readers</a></li>
|
||
<li><a class="reference internal" href="#parsers">Parsers</a></li>
|
||
<li><a class="reference internal" href="#transformer">Transformer</a></li>
|
||
<li><a class="reference internal" href="#writers">Writers</a></li>
|
||
<li><a class="reference internal" href="#input-output">Input/Output</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#docutils-package-structure">Docutils Package Structure</a></li>
|
||
<li><a class="reference internal" href="#front-end-tools">Front-End Tools</a></li>
|
||
<li><a class="reference internal" href="#document-tree">Document Tree</a></li>
|
||
<li><a class="reference internal" href="#error-handling">Error Handling</a></li>
|
||
<li><a class="reference internal" href="#python-source-reader">Python Source Reader</a><ul>
|
||
<li><a class="reference internal" href="#processing-model">Processing Model</a></li>
|
||
<li><a class="reference internal" href="#ast-mining">AST Mining</a></li>
|
||
<li><a class="reference internal" href="#docstring-extraction-rules">Docstring Extraction Rules</a><ul>
|
||
<li><a class="reference internal" href="#attribute-docstrings">Attribute Docstrings</a></li>
|
||
<li><a class="reference internal" href="#additional-docstrings">Additional Docstrings</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#choice-of-docstring-format">Choice of Docstring Format</a></li>
|
||
<li><a class="reference internal" href="#identifier-cross-references">Identifier Cross-References</a></li>
|
||
<li><a class="reference internal" href="#stylist-transforms">Stylist Transforms</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#project-web-site">Project Web Site</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="rejection-notice">
|
||
<h2><a class="toc-backref" href="#rejection-notice" role="doc-backlink">Rejection Notice</a></h2>
|
||
<p>While this may serve as an interesting design document for the
|
||
now-independent docutils, it is no longer slated for inclusion in the
|
||
standard library.</p>
|
||
</section>
|
||
<section id="abstract">
|
||
<h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2>
|
||
<p>This PEP documents design issues and implementation details for
|
||
Docutils, a Python Docstring Processing System (DPS). The rationale
|
||
and high-level concepts of a DPS are documented in <a class="pep reference internal" href="../pep-0256/" title="PEP 256 – Docstring Processing System Framework">PEP 256</a>, “Docstring
|
||
Processing System Framework”. Also 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”.</p>
|
||
<p>Docutils is being designed modularly so that any of its components can
|
||
be replaced easily. In addition, Docutils is not limited to the
|
||
processing of Python docstrings; it processes standalone documents as
|
||
well, in several contexts.</p>
|
||
<p>No changes to the core Python language are required by this PEP. Its
|
||
deliverables consist of a package for the standard library and its
|
||
documentation.</p>
|
||
</section>
|
||
<section id="specification">
|
||
<h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2>
|
||
<section id="docutils-project-model">
|
||
<h3><a class="toc-backref" href="#docutils-project-model" role="doc-backlink">Docutils Project Model</a></h3>
|
||
<p>Project components and data flow:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">+---------------------------+</span>
|
||
<span class="o">|</span> <span class="n">Docutils</span><span class="p">:</span> <span class="o">|</span>
|
||
<span class="o">|</span> <span class="n">docutils</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">Publisher</span><span class="p">,</span> <span class="o">|</span>
|
||
<span class="o">|</span> <span class="n">docutils</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">publish_</span><span class="o">*</span><span class="p">()</span> <span class="o">|</span>
|
||
<span class="o">+---------------------------+</span>
|
||
<span class="o">/</span> <span class="o">|</span> \
|
||
<span class="o">/</span> <span class="o">|</span> \
|
||
<span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">5</span> <span class="o">/</span> <span class="mi">6</span> <span class="o">|</span> \ <span class="mi">7</span>
|
||
<span class="o">+--------+</span> <span class="o">+-------------+</span> <span class="o">+--------+</span>
|
||
<span class="o">|</span> <span class="n">READER</span> <span class="o">|</span> <span class="o">----></span> <span class="o">|</span> <span class="n">TRANSFORMER</span> <span class="o">|</span> <span class="o">====></span> <span class="o">|</span> <span class="n">WRITER</span> <span class="o">|</span>
|
||
<span class="o">+--------+</span> <span class="o">+-------------+</span> <span class="o">+--------+</span>
|
||
<span class="o">/</span> \\ <span class="o">|</span>
|
||
<span class="o">/</span> \\ <span class="o">|</span>
|
||
<span class="mi">2</span> <span class="o">/</span> <span class="mi">4</span> \\ <span class="mi">8</span> <span class="o">|</span>
|
||
<span class="o">+-------+</span> <span class="o">+--------+</span> <span class="o">+--------+</span>
|
||
<span class="o">|</span> <span class="n">INPUT</span> <span class="o">|</span> <span class="o">|</span> <span class="n">PARSER</span> <span class="o">|</span> <span class="o">|</span> <span class="n">OUTPUT</span> <span class="o">|</span>
|
||
<span class="o">+-------+</span> <span class="o">+--------+</span> <span class="o">+--------+</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The numbers above each component indicate the path a document’s data
|
||
takes. Double-width lines between Reader & Parser and between
|
||
Transformer & Writer indicate that data sent along these paths should
|
||
be standard (pure & unextended) Docutils doc trees. Single-width
|
||
lines signify that internal tree extensions or completely unrelated
|
||
representations are possible, but they must be supported at both ends.</p>
|
||
<section id="publisher">
|
||
<h4><a class="toc-backref" href="#publisher" role="doc-backlink">Publisher</a></h4>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">docutils.core</span></code> module contains a “Publisher” facade class and
|
||
several convenience functions: “publish_cmdline()” (for command-line
|
||
front ends), “publish_file()” (for programmatic use with file-like
|
||
I/O), and “publish_string()” (for programmatic use with string I/O).
|
||
The Publisher class encapsulates the high-level logic of a Docutils
|
||
system. The Publisher class has overall responsibility for
|
||
processing, controlled by the <code class="docutils literal notranslate"><span class="pre">Publisher.publish()</span></code> method:</p>
|
||
<ol class="arabic simple">
|
||
<li>Set up internal settings (may include config files & command-line
|
||
options) and I/O objects.</li>
|
||
<li>Call the Reader object to read data from the source Input object
|
||
and parse the data with the Parser object. A document object is
|
||
returned.</li>
|
||
<li>Set up and apply transforms via the Transformer object attached to
|
||
the document.</li>
|
||
<li>Call the Writer object which translates the document to the final
|
||
output format and writes the formatted data to the destination
|
||
Output object. Depending on the Output object, the output may be
|
||
returned from the Writer, and then from the <code class="docutils literal notranslate"><span class="pre">publish()</span></code> method.</li>
|
||
</ol>
|
||
<p>Calling the “publish” function (or instantiating a “Publisher” object)
|
||
with component names will result in default behavior. For custom
|
||
behavior (customizing component settings), create custom component
|
||
objects first, and pass <em>them</em> to the Publisher or <code class="docutils literal notranslate"><span class="pre">publish_*</span></code>
|
||
convenience functions.</p>
|
||
</section>
|
||
<section id="readers">
|
||
<h4><a class="toc-backref" href="#readers" role="doc-backlink">Readers</a></h4>
|
||
<p>Readers understand the input context (where the data is coming from),
|
||
send the whole input or discrete “chunks” to the parser, and provide
|
||
the context to bind the chunks together back into a cohesive whole.</p>
|
||
<p>Each reader is a module or package exporting a “Reader” class with a
|
||
“read” method. The base “Reader” class can be found in the
|
||
<code class="docutils literal notranslate"><span class="pre">docutils/readers/__init__.py</span></code> module.</p>
|
||
<p>Most Readers will have to be told what parser to use. So far (see the
|
||
list of examples below), only the Python Source Reader (“PySource”;
|
||
still incomplete) will be able to determine the parser on its own.</p>
|
||
<p>Responsibilities:</p>
|
||
<ul class="simple">
|
||
<li>Get input text from the source I/O.</li>
|
||
<li>Pass the input text to the parser, along with a fresh <a class="reference internal" href="#document-tree">document
|
||
tree</a> root.</li>
|
||
</ul>
|
||
<p>Examples:</p>
|
||
<ul>
|
||
<li>Standalone (Raw/Plain): Just read a text file and process it.
|
||
The reader needs to be told which parser to use.<p>The “Standalone Reader” has been implemented in module
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.readers.standalone</span></code>.</p>
|
||
</li>
|
||
<li>Python Source: See <a class="reference internal" href="#python-source-reader">Python Source Reader</a> below. This Reader is
|
||
currently in development in the Docutils sandbox.</li>
|
||
<li>Email: <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc822.html"><strong>RFC 822</strong></a> headers, quoted excerpts, signatures, MIME parts.</li>
|
||
<li>PEP: <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc822.html"><strong>RFC 822</strong></a> headers, “PEP xxxx” and “RFC xxxx” conversion to URIs.
|
||
The “PEP Reader” has been implemented in module
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.readers.pep</span></code>; see <a class="pep reference internal" href="../pep-0287/" title="PEP 287 – reStructuredText Docstring Format">PEP 287</a> and <a class="pep reference internal" href="../pep-0012/" title="PEP 12 – Sample reStructuredText PEP Template">PEP 12</a>.</li>
|
||
<li>Wiki: Global reference lookups of “wiki links” incorporated into
|
||
transforms. (CamelCase only or unrestricted?) Lazy
|
||
indentation?</li>
|
||
<li>Web Page: As standalone, but recognize meta fields as meta tags.
|
||
Support for templates of some sort? (After <code class="docutils literal notranslate"><span class="pre"><body></span></code>, before
|
||
<code class="docutils literal notranslate"><span class="pre"></body></span></code>?)</li>
|
||
<li>FAQ: Structured “question & answer(s)” constructs.</li>
|
||
<li>Compound document: Merge chapters into a book. Master manifest
|
||
file?</li>
|
||
</ul>
|
||
</section>
|
||
<section id="parsers">
|
||
<h4><a class="toc-backref" href="#parsers" role="doc-backlink">Parsers</a></h4>
|
||
<p>Parsers analyze their input and produce a Docutils <a class="reference internal" href="#document-tree">document tree</a>.
|
||
They don’t know or care anything about the source or destination of
|
||
the data.</p>
|
||
<p>Each input parser is a module or package exporting a “Parser” class
|
||
with a “parse” method. The base “Parser” class can be found in the
|
||
<code class="docutils literal notranslate"><span class="pre">docutils/parsers/__init__.py</span></code> module.</p>
|
||
<p>Responsibilities: Given raw input text and a doctree root node,
|
||
populate the doctree by parsing the input text.</p>
|
||
<p>Example: The only parser implemented so far is for the
|
||
reStructuredText markup. It is implemented in the
|
||
<code class="docutils literal notranslate"><span class="pre">docutils/parsers/rst/</span></code> package.</p>
|
||
<p>The development and integration of other parsers is possible and
|
||
encouraged.</p>
|
||
</section>
|
||
<section id="transformer">
|
||
<span id="transforms"></span><h4><a class="toc-backref" href="#transformer" role="doc-backlink">Transformer</a></h4>
|
||
<p>The Transformer class, in <code class="docutils literal notranslate"><span class="pre">docutils/transforms/__init__.py</span></code>, stores
|
||
transforms and applies them to documents. A transformer object is
|
||
attached to every new document tree. The <a class="reference internal" href="#publisher">Publisher</a> calls
|
||
<code class="docutils literal notranslate"><span class="pre">Transformer.apply_transforms()</span></code> to apply all stored transforms to
|
||
the document tree. Transforms change the document tree from one form
|
||
to another, add to the tree, or prune it. Transforms resolve
|
||
references and footnote numbers, process interpreted text, and do
|
||
other context-sensitive processing.</p>
|
||
<p>Some transforms are specific to components (Readers, Parser, Writers,
|
||
Input, Output). Standard component-specific transforms are specified
|
||
in the <code class="docutils literal notranslate"><span class="pre">default_transforms</span></code> attribute of component classes. After
|
||
the Reader has finished processing, the <a class="reference internal" href="#publisher">Publisher</a> calls
|
||
<code class="docutils literal notranslate"><span class="pre">Transformer.populate_from_components()</span></code> with a list of components
|
||
and all default transforms are stored.</p>
|
||
<p>Each transform is a class in a module in the <code class="docutils literal notranslate"><span class="pre">docutils/transforms/</span></code>
|
||
package, a subclass of <code class="docutils literal notranslate"><span class="pre">docutils.transforms.Transform</span></code>. Transform
|
||
classes each have a <code class="docutils literal notranslate"><span class="pre">default_priority</span></code> attribute which is used by
|
||
the Transformer to apply transforms in order (low to high). The
|
||
default priority can be overridden when adding transforms to the
|
||
Transformer object.</p>
|
||
<p>Transformer responsibilities:</p>
|
||
<ul class="simple">
|
||
<li>Apply transforms to the document tree, in priority order.</li>
|
||
<li>Store a mapping of component type name (‘reader’, ‘writer’, etc.) to
|
||
component objects. These are used by certain transforms (such as
|
||
“components.Filter”) to determine suitability.</li>
|
||
</ul>
|
||
<p>Transform responsibilities:</p>
|
||
<ul class="simple">
|
||
<li>Modify a doctree in-place, either purely transforming one structure
|
||
into another, or adding new structures based on the doctree and/or
|
||
external data.</li>
|
||
</ul>
|
||
<p>Examples of transforms (in the <code class="docutils literal notranslate"><span class="pre">docutils/transforms/</span></code> package):</p>
|
||
<ul class="simple">
|
||
<li>frontmatter.DocInfo: Conversion of document metadata (bibliographic
|
||
information).</li>
|
||
<li>references.AnonymousHyperlinks: Resolution of anonymous references
|
||
to corresponding targets.</li>
|
||
<li>parts.Contents: Generates a table of contents for a document.</li>
|
||
<li>document.Merger: Combining multiple populated doctrees into one.
|
||
(Not yet implemented or fully understood.)</li>
|
||
<li>document.Splitter: Splits a document into a tree-structure of
|
||
subdocuments, perhaps by section. It will have to transform
|
||
references appropriately. (Neither implemented not remotely
|
||
understood.)</li>
|
||
<li>components.Filter: Includes or excludes elements which depend on a
|
||
specific Docutils component.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="writers">
|
||
<h4><a class="toc-backref" href="#writers" role="doc-backlink">Writers</a></h4>
|
||
<p>Writers produce the final output (HTML, XML, TeX, etc.). Writers
|
||
translate the internal <a class="reference internal" href="#document-tree">document tree</a> structure into the final data
|
||
format, possibly running Writer-specific <a class="reference internal" href="#transforms">transforms</a> first.</p>
|
||
<p>By the time the document gets to the Writer, it should be in final
|
||
form. The Writer’s job is simply (and only) to translate from the
|
||
Docutils doctree structure to the target format. Some small
|
||
transforms may be required, but they should be local and
|
||
format-specific.</p>
|
||
<p>Each writer is a module or package exporting a “Writer” class with a
|
||
“write” method. The base “Writer” class can be found in the
|
||
<code class="docutils literal notranslate"><span class="pre">docutils/writers/__init__.py</span></code> module.</p>
|
||
<p>Responsibilities:</p>
|
||
<ul class="simple">
|
||
<li>Translate doctree(s) into specific output formats.<ul>
|
||
<li>Transform references into format-native forms.</li>
|
||
</ul>
|
||
</li>
|
||
<li>Write the translated output to the destination I/O.</li>
|
||
</ul>
|
||
<p>Examples:</p>
|
||
<ul class="simple">
|
||
<li>XML: Various forms, such as:<ul>
|
||
<li>Docutils XML (an expression of the internal document tree,
|
||
implemented as <code class="docutils literal notranslate"><span class="pre">docutils.writers.docutils_xml</span></code>).</li>
|
||
<li>DocBook (being implemented in the Docutils sandbox).</li>
|
||
</ul>
|
||
</li>
|
||
<li>HTML (XHTML implemented as <code class="docutils literal notranslate"><span class="pre">docutils.writers.html4css1</span></code>).</li>
|
||
<li>PDF (a ReportLabs interface is being developed in the Docutils
|
||
sandbox).</li>
|
||
<li>TeX (a LaTeX Writer is being implemented in the sandbox).</li>
|
||
<li>Docutils-native pseudo-XML (implemented as
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.writers.pseudoxml</span></code>, used for testing).</li>
|
||
<li>Plain text</li>
|
||
<li>reStructuredText?</li>
|
||
</ul>
|
||
</section>
|
||
<section id="input-output">
|
||
<h4><a class="toc-backref" href="#input-output" role="doc-backlink">Input/Output</a></h4>
|
||
<p>I/O classes provide a uniform API for low-level input and output.
|
||
Subclasses will exist for a variety of input/output mechanisms.
|
||
However, they can be considered an implementation detail. Most
|
||
applications should be satisfied using one of the convenience
|
||
functions associated with the <a class="reference internal" href="#publisher">Publisher</a>.</p>
|
||
<p>I/O classes are currently in the preliminary stages; there’s a lot of
|
||
work yet to be done. Issues:</p>
|
||
<ul class="simple">
|
||
<li>How to represent multi-file input (files & directories) in the API?</li>
|
||
<li>How to represent multi-file output? Perhaps “Writer” variants, one
|
||
for each output distribution type? Or Output objects with
|
||
associated transforms?</li>
|
||
</ul>
|
||
<p>Responsibilities:</p>
|
||
<ul class="simple">
|
||
<li>Read data from the input source (Input objects) or write data to the
|
||
output destination (Output objects).</li>
|
||
</ul>
|
||
<p>Examples of input sources:</p>
|
||
<ul class="simple">
|
||
<li>A single file on disk or a stream (implemented as
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.io.FileInput</span></code>).</li>
|
||
<li>Multiple files on disk (<code class="docutils literal notranslate"><span class="pre">MultiFileInput</span></code>?).</li>
|
||
<li>Python source files: modules and packages.</li>
|
||
<li>Python strings, as received from a client application
|
||
(implemented as <code class="docutils literal notranslate"><span class="pre">docutils.io.StringInput</span></code>).</li>
|
||
</ul>
|
||
<p>Examples of output destinations:</p>
|
||
<ul class="simple">
|
||
<li>A single file on disk or a stream (implemented as
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.io.FileOutput</span></code>).</li>
|
||
<li>A tree of directories and files on disk.</li>
|
||
<li>A Python string, returned to a client application (implemented as
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.io.StringOutput</span></code>).</li>
|
||
<li>No output; useful for programmatic applications where only a portion
|
||
of the normal output is to be used (implemented as
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.io.NullOutput</span></code>).</li>
|
||
<li>A single tree-shaped data structure in memory.</li>
|
||
<li>Some other set of data structures in memory.</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="docutils-package-structure">
|
||
<h3><a class="toc-backref" href="#docutils-package-structure" role="doc-backlink">Docutils Package Structure</a></h3>
|
||
<ul>
|
||
<li>Package “docutils”.<ul>
|
||
<li>Module “__init__.py” contains: class “Component”, a base class for
|
||
Docutils components; class “SettingsSpec”, a base class for
|
||
specifying runtime settings (used by docutils.frontend); and class
|
||
“TransformSpec”, a base class for specifying transforms.</li>
|
||
<li>Module “docutils.core” contains facade class “Publisher” and
|
||
convenience functions. See <a class="reference internal" href="#publisher">Publisher</a> above.</li>
|
||
<li>Module “docutils.frontend” provides runtime settings support, for
|
||
programmatic use and front-end tools (including configuration file
|
||
support, and command-line argument and option processing).</li>
|
||
<li>Module “docutils.io” provides a uniform API for low-level input
|
||
and output. See <a class="reference internal" href="#input-output">Input/Output</a> above.</li>
|
||
<li>Module “docutils.nodes” contains the Docutils document tree
|
||
element class library plus tree-traversal Visitor pattern base
|
||
classes. See <a class="reference internal" href="#document-tree">Document Tree</a> below.</li>
|
||
<li>Module “docutils.statemachine” contains a finite state machine
|
||
specialized for regular-expression-based text filters and parsers.
|
||
The reStructuredText parser implementation is based on this
|
||
module.</li>
|
||
<li>Module “docutils.urischemes” contains a mapping of known URI
|
||
schemes (“http”, “ftp”, “mail”, etc.).</li>
|
||
<li>Module “docutils.utils” contains utility functions and classes,
|
||
including a logger class (“Reporter”; see <a class="reference internal" href="#error-handling">Error Handling</a>
|
||
below).</li>
|
||
<li>Package “docutils.parsers”: markup <a class="reference internal" href="#parsers">parsers</a>.<ul class="simple">
|
||
<li>Function “get_parser_class(parser_name)” returns a parser module
|
||
by name. Class “Parser” is the base class of specific parsers.
|
||
(<code class="docutils literal notranslate"><span class="pre">docutils/parsers/__init__.py</span></code>)</li>
|
||
<li>Package “docutils.parsers.rst”: the reStructuredText parser.</li>
|
||
<li>Alternate markup parsers may be added.</li>
|
||
</ul>
|
||
<p>See <a class="reference internal" href="#parsers">Parsers</a> above.</p>
|
||
</li>
|
||
<li>Package “docutils.readers”: context-aware input readers.<ul class="simple">
|
||
<li>Function “get_reader_class(reader_name)” returns a reader module
|
||
by name or alias. Class “Reader” is the base class of specific
|
||
readers. (<code class="docutils literal notranslate"><span class="pre">docutils/readers/__init__.py</span></code>)</li>
|
||
<li>Module “docutils.readers.standalone” reads independent document
|
||
files.</li>
|
||
<li>Module “docutils.readers.pep” reads PEPs (Python Enhancement
|
||
Proposals).</li>
|
||
<li>Readers to be added for: Python source code (structure &
|
||
docstrings), email, FAQ, and perhaps Wiki and others.</li>
|
||
</ul>
|
||
<p>See <a class="reference internal" href="#readers">Readers</a> above.</p>
|
||
</li>
|
||
<li>Package “docutils.writers”: output format writers.<ul class="simple">
|
||
<li>Function “get_writer_class(writer_name)” returns a writer module
|
||
by name. Class “Writer” is the base class of specific writers.
|
||
(<code class="docutils literal notranslate"><span class="pre">docutils/writers/__init__.py</span></code>)</li>
|
||
<li>Module “docutils.writers.html4css1” is a simple HyperText Markup
|
||
Language document tree writer for HTML 4.01 and CSS1.</li>
|
||
<li>Module “docutils.writers.docutils_xml” writes the internal
|
||
document tree in XML form.</li>
|
||
<li>Module “docutils.writers.pseudoxml” is a simple internal
|
||
document tree writer; it writes indented pseudo-XML.</li>
|
||
<li>Writers to be added: HTML 3.2 or 4.01-loose, XML (various forms,
|
||
such as DocBook), PDF, TeX, plaintext, reStructuredText, and
|
||
perhaps others.</li>
|
||
</ul>
|
||
<p>See <a class="reference internal" href="#writers">Writers</a> above.</p>
|
||
</li>
|
||
<li>Package “docutils.transforms”: tree transform classes.<ul class="simple">
|
||
<li>Class “Transformer” stores transforms and applies them to
|
||
document trees. (<code class="docutils literal notranslate"><span class="pre">docutils/transforms/__init__.py</span></code>)</li>
|
||
<li>Class “Transform” is the base class of specific transforms.
|
||
(<code class="docutils literal notranslate"><span class="pre">docutils/transforms/__init__.py</span></code>)</li>
|
||
<li>Each module contains related transform classes.</li>
|
||
</ul>
|
||
<p>See <a class="reference internal" href="#transforms">Transforms</a> above.</p>
|
||
</li>
|
||
<li>Package “docutils.languages”: Language modules contain
|
||
language-dependent strings and mappings. They are named for their
|
||
language identifier (as defined in <a class="reference internal" href="#choice-of-docstring-format">Choice of Docstring Format</a>
|
||
below), converting dashes to underscores.<ul class="simple">
|
||
<li>Function “get_language(language_code)”, returns matching
|
||
language module. (<code class="docutils literal notranslate"><span class="pre">docutils/languages/__init__.py</span></code>)</li>
|
||
<li>Modules: en.py (English), de.py (German), fr.py (French), it.py
|
||
(Italian), sk.py (Slovak), sv.py (Swedish).</li>
|
||
<li>Other languages to be added.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>Third-party modules: “extras” directory. These modules are
|
||
installed only if they’re not already present in the Python
|
||
installation.<ul class="simple">
|
||
<li><code class="docutils literal notranslate"><span class="pre">extras/optparse.py</span></code> and <code class="docutils literal notranslate"><span class="pre">extras/textwrap.py</span></code> provide
|
||
option parsing and command-line help; from Greg Ward’s
|
||
<a class="reference external" href="http://optik.sf.net/">http://optik.sf.net/</a> project, included for convenience.</li>
|
||
<li><code class="docutils literal notranslate"><span class="pre">extras/roman.py</span></code> contains Roman numeral conversion routines.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="front-end-tools">
|
||
<h3><a class="toc-backref" href="#front-end-tools" role="doc-backlink">Front-End Tools</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">tools/</span></code> directory contains several front ends for common
|
||
Docutils processing. See <a class="reference external" href="http://docutils.sourceforge.net/docs/user/tools.html">Docutils Front-End Tools</a> for details.</p>
|
||
</section>
|
||
<section id="document-tree">
|
||
<h3><a class="toc-backref" href="#document-tree" role="doc-backlink">Document Tree</a></h3>
|
||
<p>A single intermediate data structure is used internally by Docutils,
|
||
in the interfaces between components; it is defined in the
|
||
<code class="docutils literal notranslate"><span class="pre">docutils.nodes</span></code> module. It is not required that this data
|
||
structure be used <em>internally</em> by any of the components, just
|
||
<em>between</em> components as outlined in the diagram in the <a class="reference internal" href="#docutils-project-model">Docutils
|
||
Project Model</a> above.</p>
|
||
<p>Custom node types are allowed, provided that either (a) a transform
|
||
converts them to standard Docutils nodes before they reach the Writer
|
||
proper, or (b) the custom node is explicitly supported by certain
|
||
Writers, and is wrapped in a filtered “pending” node. An example of
|
||
condition (a) is the <a class="reference internal" href="#python-source-reader">Python Source Reader</a> (see below), where a
|
||
“stylist” transform converts custom nodes. The HTML <code class="docutils literal notranslate"><span class="pre"><meta></span></code> tag is
|
||
an example of condition (b); it is supported by the HTML Writer but
|
||
not by others. The reStructuredText “meta” directive creates a
|
||
“pending” node, which contains knowledge that the embedded “meta” node
|
||
can only be handled by HTML-compatible writers. The “pending” node is
|
||
resolved by the <code class="docutils literal notranslate"><span class="pre">docutils.transforms.components.Filter</span></code> transform,
|
||
which checks that the calling writer supports HTML; if it doesn’t, the
|
||
“pending” node (and enclosed “meta” node) is removed from the
|
||
document.</p>
|
||
<p>The document tree data structure is similar to a DOM tree, but with
|
||
specific node names (classes) instead of DOM’s generic nodes. The
|
||
schema is documented in an XML DTD (eXtensible Markup Language
|
||
Document Type Definition), which comes in two parts:</p>
|
||
<ul class="simple">
|
||
<li>the Docutils Generic DTD, <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/docutils.dtd">docutils.dtd</a>, and</li>
|
||
<li>the OASIS Exchange Table Model, <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/soextblx.dtd">soextbl.dtd</a>.</li>
|
||
</ul>
|
||
<p>The DTD defines a rich set of elements, suitable for many input and
|
||
output formats. The DTD retains all information necessary to
|
||
reconstruct the original input text, or a reasonable facsimile
|
||
thereof.</p>
|
||
<p>See <a class="reference external" href="http://docutils.sourceforge.net/docs/ref/doctree.html">The Docutils Document Tree</a> for details (incomplete).</p>
|
||
</section>
|
||
<section id="error-handling">
|
||
<h3><a class="toc-backref" href="#error-handling" role="doc-backlink">Error Handling</a></h3>
|
||
<p>When the parser encounters an error in markup, it inserts a system
|
||
message (DTD element “system_message”). There are five levels of
|
||
system messages:</p>
|
||
<ul class="simple">
|
||
<li>Level-0, “DEBUG”: an internal reporting issue. There is no effect
|
||
on the processing. Level-0 system messages are handled separately
|
||
from the others.</li>
|
||
<li>Level-1, “INFO”: a minor issue that can be ignored. There is little
|
||
or no effect on the processing. Typically level-1 system messages
|
||
are not reported.</li>
|
||
<li>Level-2, “WARNING”: an issue that should be addressed. If ignored,
|
||
there may be minor problems with the output. Typically level-2
|
||
system messages are reported but do not halt processing</li>
|
||
<li>Level-3, “ERROR”: a major issue that should be addressed. If
|
||
ignored, the output will contain unpredictable errors. Typically
|
||
level-3 system messages are reported but do not halt processing</li>
|
||
<li>Level-4, “SEVERE”: a critical error that must be addressed.
|
||
Typically level-4 system messages are turned into exceptions which
|
||
halt processing. If ignored, the output will contain severe errors.</li>
|
||
</ul>
|
||
<p>Although the initial message levels were devised independently, they
|
||
have a strong correspondence to <a class="reference external" href="http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html#error_cond_severity">VMS error condition severity
|
||
levels</a>; the names in quotes for levels 1 through 4 were borrowed
|
||
from VMS. Error handling has since been influenced by the <a class="reference external" href="http://logging.apache.org/log4j/docs/index.html">log4j
|
||
project</a>.</p>
|
||
</section>
|
||
<section id="python-source-reader">
|
||
<h3><a class="toc-backref" href="#python-source-reader" role="doc-backlink">Python Source Reader</a></h3>
|
||
<p>The Python Source Reader (“PySource”) is the Docutils component that
|
||
reads Python source files, extracts docstrings in context, then
|
||
parses, links, and assembles the docstrings into a cohesive whole. It
|
||
is a major and non-trivial component, currently under experimental
|
||
development in the Docutils sandbox. High-level design issues are
|
||
presented here.</p>
|
||
<section id="processing-model">
|
||
<h4><a class="toc-backref" href="#processing-model" role="doc-backlink">Processing Model</a></h4>
|
||
<p>This model will evolve over time, incorporating experience and
|
||
discoveries.</p>
|
||
<ol class="arabic simple">
|
||
<li>The PySource Reader uses an Input class to read in Python packages
|
||
and modules, into a tree of strings.</li>
|
||
<li>The Python modules are parsed, converting the tree of strings into
|
||
a tree of abstract syntax trees with docstring nodes.</li>
|
||
<li>The abstract syntax trees are converted into an internal
|
||
representation of the packages/modules. Docstrings are extracted,
|
||
as well as code structure details. See <a class="reference internal" href="#ast-mining">AST Mining</a> below.
|
||
Namespaces are constructed for lookup in step 6.</li>
|
||
<li>One at a time, the docstrings are parsed, producing standard
|
||
Docutils doctrees.</li>
|
||
<li>PySource assembles all the individual docstrings’ doctrees into a
|
||
Python-specific custom Docutils tree paralleling the
|
||
package/module/class structure; this is a custom Reader-specific
|
||
internal representation (see the <a class="reference external" href="http://docutils.sourceforge.net/docs/dev/pysource.dtd">Docutils Python Source DTD</a>).
|
||
Namespaces must be merged: Python identifiers, hyperlink targets.</li>
|
||
<li>Cross-references from docstrings (interpreted text) to Python
|
||
identifiers are resolved according to the Python namespace lookup
|
||
rules. See <a class="reference internal" href="#identifier-cross-references">Identifier Cross-References</a> below.</li>
|
||
<li>A “Stylist” transform is applied to the custom doctree (by the
|
||
<a class="reference internal" href="#transformer">Transformer</a>), custom nodes are rendered using standard nodes as
|
||
primitives, and a standard document tree is emitted. See <a class="reference internal" href="#stylist-transforms">Stylist
|
||
Transforms</a> below.</li>
|
||
<li>Other transforms are applied to the standard doctree by the
|
||
<a class="reference internal" href="#transformer">Transformer</a>.</li>
|
||
<li>The standard doctree is sent to a Writer, which translates the
|
||
document into a concrete format (HTML, PDF, etc.).</li>
|
||
<li>The Writer uses an Output class to write the resulting data to its
|
||
destination (disk file, directories and files, etc.).</li>
|
||
</ol>
|
||
</section>
|
||
<section id="ast-mining">
|
||
<h4><a class="toc-backref" href="#ast-mining" role="doc-backlink">AST Mining</a></h4>
|
||
<p>Abstract Syntax Tree mining code will be written (or adapted) that
|
||
scans a parsed Python module, and returns an ordered tree containing
|
||
the names, docstrings (including attribute and additional docstrings;
|
||
see below), and additional info (in parentheses below) of all of the
|
||
following objects:</p>
|
||
<ul class="simple">
|
||
<li>packages</li>
|
||
<li>modules</li>
|
||
<li>module attributes (+ initial values)</li>
|
||
<li>classes (+ inheritance)</li>
|
||
<li>class attributes (+ initial values)</li>
|
||
<li>instance attributes (+ initial values)</li>
|
||
<li>methods (+ parameters & defaults)</li>
|
||
<li>functions (+ parameters & defaults)</li>
|
||
</ul>
|
||
<p>(Extract comments too? For example, comments at the start of a module
|
||
would be a good place for bibliographic field lists.)</p>
|
||
<p>In order to evaluate interpreted text cross-references, namespaces for
|
||
each of the above will also be required.</p>
|
||
<p>See the python-dev/docstring-develop thread “AST mining”, started on
|
||
2001-08-14.</p>
|
||
</section>
|
||
<section id="docstring-extraction-rules">
|
||
<h4><a class="toc-backref" href="#docstring-extraction-rules" role="doc-backlink">Docstring Extraction Rules</a></h4>
|
||
<ol class="arabic">
|
||
<li>What to examine:<ol class="loweralpha simple">
|
||
<li>If the “<code class="docutils literal notranslate"><span class="pre">__all__</span></code>” variable is present in the module being
|
||
documented, only identifiers listed in “<code class="docutils literal notranslate"><span class="pre">__all__</span></code>” are
|
||
examined for docstrings.</li>
|
||
<li>In the absence of “<code class="docutils literal notranslate"><span class="pre">__all__</span></code>”, all identifiers are examined,
|
||
except those whose names are private (names begin with “_” but
|
||
don’t begin and end with “__”).</li>
|
||
<li>1a and 1b can be overridden by runtime settings.</li>
|
||
</ol>
|
||
</li>
|
||
<li>Where:<p>Docstrings are string literal expressions, and are recognized in
|
||
the following places within Python modules:</p>
|
||
<ol class="loweralpha simple">
|
||
<li>At the beginning of a module, function definition, class
|
||
definition, or method definition, after any comments. This is
|
||
the standard for Python <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> attributes.</li>
|
||
<li>Immediately following a simple assignment at the top level of a
|
||
module, class definition, or <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method definition,
|
||
after any comments. See <a class="reference internal" href="#attribute-docstrings">Attribute Docstrings</a> below.</li>
|
||
<li>Additional string literals found immediately after the
|
||
docstrings in (a) and (b) will be recognized, extracted, and
|
||
concatenated. See <a class="reference internal" href="#additional-docstrings">Additional Docstrings</a> below.</li>
|
||
<li>@@@ 2.2-style “properties” with attribute docstrings? Wait for
|
||
syntax?</li>
|
||
</ol>
|
||
</li>
|
||
<li>How:<p>Whenever possible, Python modules should be parsed by Docutils, not
|
||
imported. There are several reasons:</p>
|
||
<ul class="simple">
|
||
<li>Importing untrusted code is inherently insecure.</li>
|
||
<li>Information from the source is lost when using introspection to
|
||
examine an imported module, such as comments and the order of
|
||
definitions.</li>
|
||
<li>Docstrings are to be recognized in places where the byte-code
|
||
compiler ignores string literal expressions (2b and 2c above),
|
||
meaning importing the module will lose these docstrings.</li>
|
||
</ul>
|
||
<p>Of course, standard Python parsing tools such as the “parser”
|
||
library module should be used.</p>
|
||
<p>When the Python source code for a module is not available
|
||
(i.e. only the <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> file exists) or for C extension modules, to
|
||
access docstrings the module can only be imported, and any
|
||
limitations must be lived with.</p>
|
||
</li>
|
||
</ol>
|
||
<p>Since attribute docstrings and additional docstrings are ignored by
|
||
the Python byte-code compiler, no namespace pollution or runtime bloat
|
||
will result from their use. They are not assigned to <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> or
|
||
to any other attribute. The initial parsing of a module may take a
|
||
slight performance hit.</p>
|
||
<section id="attribute-docstrings">
|
||
<h5><a class="toc-backref" href="#attribute-docstrings" role="doc-backlink">Attribute Docstrings</a></h5>
|
||
<p>(This is a simplified version of <a class="pep reference internal" href="../pep-0224/" title="PEP 224 – Attribute Docstrings">PEP 224</a>.)</p>
|
||
<p>A string literal immediately following an assignment statement is
|
||
interpreted by the docstring extraction machinery as the docstring of
|
||
the target of the assignment statement, under the following
|
||
conditions:</p>
|
||
<ol class="arabic">
|
||
<li>The assignment must be in one of the following contexts:<ol class="loweralpha simple">
|
||
<li>At the top level of a module (i.e., not nested inside a compound
|
||
statement such as a loop or conditional): a module attribute.</li>
|
||
<li>At the top level of a class definition: a class attribute.</li>
|
||
<li>At the top level of the “<code class="docutils literal notranslate"><span class="pre">__init__</span></code>” method definition of a
|
||
class: an instance attribute. Instance attributes assigned in
|
||
other methods are assumed to be implementation details. (@@@
|
||
<code class="docutils literal notranslate"><span class="pre">__new__</span></code> methods?)</li>
|
||
<li>A function attribute assignment at the top level of a module or
|
||
class definition.</li>
|
||
</ol>
|
||
<p>Since each of the above contexts are at the top level (i.e., in the
|
||
outermost suite of a definition), it may be necessary to place
|
||
dummy assignments for attributes assigned conditionally or in a
|
||
loop.</p>
|
||
</li>
|
||
<li>The assignment must be to a single target, not to a list or a tuple
|
||
of targets.</li>
|
||
<li>The form of the target:<ol class="loweralpha simple">
|
||
<li>For contexts 1a and 1b above, the target must be a simple
|
||
identifier (not a dotted identifier, a subscripted expression,
|
||
or a sliced expression).</li>
|
||
<li>For context 1c above, the target must be of the form
|
||
“<code class="docutils literal notranslate"><span class="pre">self.attrib</span></code>”, where “<code class="docutils literal notranslate"><span class="pre">self</span></code>” matches the “<code class="docutils literal notranslate"><span class="pre">__init__</span></code>”
|
||
method’s first parameter (the instance parameter) and “attrib”
|
||
is a simple identifier as in 3a.</li>
|
||
<li>For context 1d above, the target must be of the form
|
||
“<code class="docutils literal notranslate"><span class="pre">name.attrib</span></code>”, where “<code class="docutils literal notranslate"><span class="pre">name</span></code>” matches an already-defined
|
||
function or method name and “attrib” is a simple identifier as
|
||
in 3a.</li>
|
||
</ol>
|
||
</li>
|
||
</ol>
|
||
<p>Blank lines may be used after attribute docstrings to emphasize the
|
||
connection between the assignment and the docstring.</p>
|
||
<p>Examples:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">g</span> <span class="o">=</span> <span class="s1">'module attribute (module-global variable)'</span>
|
||
<span class="sd">"""This is g's docstring."""</span>
|
||
|
||
<span class="k">class</span> <span class="nc">AClass</span><span class="p">:</span>
|
||
|
||
<span class="n">c</span> <span class="o">=</span> <span class="s1">'class attribute'</span>
|
||
<span class="w"> </span><span class="sd">"""This is AClass.c's docstring."""</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">"""Method __init__'s docstring."""</span>
|
||
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">i</span> <span class="o">=</span> <span class="s1">'instance attribute'</span>
|
||
<span class="w"> </span><span class="sd">"""This is self.i's docstring."""</span>
|
||
|
||
<span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
|
||
<span class="w"> </span><span class="sd">"""Function f's docstring."""</span>
|
||
<span class="k">return</span> <span class="n">x</span><span class="o">**</span><span class="mi">2</span>
|
||
|
||
<span class="n">f</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">1</span>
|
||
<span class="sd">"""Function attribute f.a's docstring."""</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="additional-docstrings">
|
||
<h5><a class="toc-backref" href="#additional-docstrings" role="doc-backlink">Additional Docstrings</a></h5>
|
||
<p>(This idea was adapted from <a class="pep reference internal" href="../pep-0216/" title="PEP 216 – Docstring Format">PEP 216</a>.)</p>
|
||
<p>Many programmers would like to make extensive use of docstrings for
|
||
API documentation. However, docstrings do take up space in the
|
||
running program, so some programmers are reluctant to “bloat up” their
|
||
code. Also, not all API documentation is applicable to interactive
|
||
environments, where <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> would be displayed.</p>
|
||
<p>Docutils’ docstring extraction tools will concatenate all string
|
||
literal expressions which appear at the beginning of a definition or
|
||
after a simple assignment. Only the first strings in definitions will
|
||
be available as <code class="docutils literal notranslate"><span class="pre">__doc__</span></code>, and can be used for brief usage text
|
||
suitable for interactive sessions; subsequent string literals and all
|
||
attribute docstrings are ignored by the Python byte-code compiler and
|
||
may contain more extensive API information.</p>
|
||
<p>Example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">function</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
|
||
<span class="w"> </span><span class="sd">"""This is __doc__, function's docstring."""</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> This is an additional docstring, ignored by the byte-code</span>
|
||
<span class="sd"> compiler, but extracted by Docutils.</span>
|
||
<span class="sd"> """</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
<aside class="topic">
|
||
<p class="topic-title">Issue: <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span></code></p>
|
||
<p>This would break “<code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span></code>” statements introduced
|
||
in Python 2.1 for multiple module docstrings (main docstring plus
|
||
additional docstring(s)). The Python Reference Manual specifies:</p>
|
||
<blockquote>
|
||
<div>A future statement must appear near the top of the module. The
|
||
only lines that can appear before a future statement are:<ul class="simple">
|
||
<li>the module docstring (if any),</li>
|
||
<li>comments,</li>
|
||
<li>blank lines, and</li>
|
||
<li>other future statements.</li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>Resolution?</p>
|
||
<ol class="arabic simple">
|
||
<li>Should we search for docstrings after a <code class="docutils literal notranslate"><span class="pre">__future__</span></code>
|
||
statement? Very ugly.</li>
|
||
<li>Redefine <code class="docutils literal notranslate"><span class="pre">__future__</span></code> statements to allow multiple preceding
|
||
string literals?</li>
|
||
<li>Or should we not even worry about this? There probably
|
||
shouldn’t be <code class="docutils literal notranslate"><span class="pre">__future__</span></code> statements in production code, after
|
||
all. Perhaps modules with <code class="docutils literal notranslate"><span class="pre">__future__</span></code> statements will simply
|
||
have to put up with the single-docstring limitation.</li>
|
||
</ol>
|
||
</aside>
|
||
</section>
|
||
</section>
|
||
<section id="choice-of-docstring-format">
|
||
<h4><a class="toc-backref" href="#choice-of-docstring-format" role="doc-backlink">Choice of Docstring Format</a></h4>
|
||
<p>Rather than force everyone to use a single docstring format, multiple
|
||
input formats are allowed by the processing system. A special
|
||
variable, <code class="docutils literal notranslate"><span class="pre">__docformat__</span></code>, may appear at the top level of a module
|
||
before any function or class definitions. Over time or through
|
||
decree, a standard format or set of formats should emerge.</p>
|
||
<p>A module’s <code class="docutils literal notranslate"><span class="pre">__docformat__</span></code> variable only applies to the objects
|
||
defined in the module’s file. In particular, the <code class="docutils literal notranslate"><span class="pre">__docformat__</span></code>
|
||
variable in a package’s <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file does not apply to objects
|
||
defined in subpackages and submodules.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">__docformat__</span></code> variable is a string containing the name of the
|
||
format being used, a case-insensitive string matching the input
|
||
parser’s module or package name (i.e., the same name as required to
|
||
“import” the module or package), or a registered alias. If no
|
||
<code class="docutils literal notranslate"><span class="pre">__docformat__</span></code> is specified, the default format is “plaintext” for
|
||
now; this may be changed to the standard format if one is ever
|
||
established.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">__docformat__</span></code> string may contain an optional second field,
|
||
separated from the format name (first field) by a single space: a
|
||
case-insensitive language identifier as defined in <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1766.html"><strong>RFC 1766</strong></a>. A
|
||
typical language identifier consists of a 2-letter language code from
|
||
<a class="reference external" href="http://lcweb.loc.gov/standards/iso639-2/englangn.html">ISO 639</a> (3-letter codes used only if no 2-letter code exists;
|
||
<span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1766.html"><strong>RFC 1766</strong></a> is currently being revised to allow 3-letter codes). If no
|
||
language identifier is specified, the default is “en” for English.
|
||
The language identifier is passed to the parser and can be used for
|
||
language-dependent markup features.</p>
|
||
</section>
|
||
<section id="identifier-cross-references">
|
||
<h4><a class="toc-backref" href="#identifier-cross-references" role="doc-backlink">Identifier Cross-References</a></h4>
|
||
<p>In Python docstrings, interpreted text is used to classify and mark up
|
||
program identifiers, such as the names of variables, functions,
|
||
classes, and modules. If the identifier alone is given, its role is
|
||
inferred implicitly according to the Python namespace lookup rules.
|
||
For functions and methods (even when dynamically assigned),
|
||
parentheses (‘()’) may be included:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>This function uses `another()` to do its work.
|
||
</pre></div>
|
||
</div>
|
||
<p>For class, instance and module attributes, dotted identifiers are used
|
||
when necessary. For example (using reStructuredText markup):</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"> 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 instances.</span>
|
||
|
||
<span class="sd"> Keep count in `Keeper.instances`, data 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="n">Keeper</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">store_data</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.store_data()`; 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 of the identifiers quoted with backquotes (“`”) will become
|
||
references to the definitions of the identifiers themselves.</p>
|
||
</section>
|
||
<section id="stylist-transforms">
|
||
<h4><a class="toc-backref" href="#stylist-transforms" role="doc-backlink">Stylist Transforms</a></h4>
|
||
<p>Stylist transforms are specialized transforms specific to the PySource
|
||
Reader. The PySource Reader doesn’t have to make any decisions as to
|
||
style; it just produces a logically constructed document tree, parsed
|
||
and linked, including custom node types. Stylist transforms
|
||
understand the custom nodes created by the Reader and convert them
|
||
into standard Docutils nodes.</p>
|
||
<p>Multiple Stylist transforms may be implemented and one can be chosen
|
||
at runtime (through a “–style” or “–stylist” command-line option).
|
||
Each Stylist transform implements a different layout or style; thus
|
||
the name. They decouple the context-understanding part of the Reader
|
||
from the layout-generating part of processing, resulting in a more
|
||
flexible and robust system. This also serves to “separate style from
|
||
content”, the SGML/XML ideal.</p>
|
||
<p>By keeping the piece of code that does the styling small and modular,
|
||
it becomes much easier for people to roll their own styles. The
|
||
“barrier to entry” is too high with existing tools; extracting the
|
||
stylist code will lower the barrier considerably.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="project-web-site">
|
||
<h2><a class="toc-backref" href="#project-web-site" role="doc-backlink">Project Web Site</a></h2>
|
||
<p>A SourceForge project has been set up for this work at
|
||
<a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a>.</p>
|
||
</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>This document borrows ideas from the archives of the <a class="reference external" href="http://www.python.org/sigs/doc-sig/">Python
|
||
Doc-SIG</a>. Thanks to all members past & present.</p>
|
||
</section>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0258.rst">https://github.com/python/peps/blob/main/peps/pep-0258.rst</a></p>
|
||
<p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0258.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="#rejection-notice">Rejection Notice</a></li>
|
||
<li><a class="reference internal" href="#abstract">Abstract</a></li>
|
||
<li><a class="reference internal" href="#specification">Specification</a><ul>
|
||
<li><a class="reference internal" href="#docutils-project-model">Docutils Project Model</a><ul>
|
||
<li><a class="reference internal" href="#publisher">Publisher</a></li>
|
||
<li><a class="reference internal" href="#readers">Readers</a></li>
|
||
<li><a class="reference internal" href="#parsers">Parsers</a></li>
|
||
<li><a class="reference internal" href="#transformer">Transformer</a></li>
|
||
<li><a class="reference internal" href="#writers">Writers</a></li>
|
||
<li><a class="reference internal" href="#input-output">Input/Output</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#docutils-package-structure">Docutils Package Structure</a></li>
|
||
<li><a class="reference internal" href="#front-end-tools">Front-End Tools</a></li>
|
||
<li><a class="reference internal" href="#document-tree">Document Tree</a></li>
|
||
<li><a class="reference internal" href="#error-handling">Error Handling</a></li>
|
||
<li><a class="reference internal" href="#python-source-reader">Python Source Reader</a><ul>
|
||
<li><a class="reference internal" href="#processing-model">Processing Model</a></li>
|
||
<li><a class="reference internal" href="#ast-mining">AST Mining</a></li>
|
||
<li><a class="reference internal" href="#docstring-extraction-rules">Docstring Extraction Rules</a><ul>
|
||
<li><a class="reference internal" href="#attribute-docstrings">Attribute Docstrings</a></li>
|
||
<li><a class="reference internal" href="#additional-docstrings">Additional Docstrings</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#choice-of-docstring-format">Choice of Docstring Format</a></li>
|
||
<li><a class="reference internal" href="#identifier-cross-references">Identifier Cross-References</a></li>
|
||
<li><a class="reference internal" href="#stylist-transforms">Stylist Transforms</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#project-web-site">Project Web Site</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-0258.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> |