Updates to PEPs 256, 257, 258, 287 by David Goodger. Some of the
titles have changed so this includes an update to PEP 0.
This commit is contained in:
Barry Warsaw
parent
4f0ce75e88
commit
0c228b0b73
|
|
@ -74,7 +74,7 @@ Index by Category
|
||||||
S 254 Making Classes Look More Like Types van Rossum
|
S 254 Making Classes Look More Like Types van Rossum
|
||||||
S 256 Docstring Processing System Framework Goodger
|
S 256 Docstring Processing System Framework Goodger
|
||||||
S 257 Docstring Conventions Goodger, van Rossum
|
S 257 Docstring Conventions Goodger, van Rossum
|
||||||
S 258 DPS Generic Implementation Details Goodger
|
S 258 Docutils Design Specification Goodger
|
||||||
S 262 Database of Installed Python Packages Kuchling
|
S 262 Database of Installed Python Packages Kuchling
|
||||||
S 263 Defining Python Source Code Encodings Lemburg
|
S 263 Defining Python Source Code Encodings Lemburg
|
||||||
S 265 Sorting Dictionaries by Value Griffin
|
S 265 Sorting Dictionaries by Value Griffin
|
||||||
|
|
@ -95,7 +95,7 @@ Index by Category
|
||||||
I 283 Python 2.3 Release Schedule van Rossum
|
I 283 Python 2.3 Release Schedule van Rossum
|
||||||
S 284 Integer for-loops Eppstein, Ewing
|
S 284 Integer for-loops Eppstein, Ewing
|
||||||
S 286 Enhanced Argument Tuples von Loewis
|
S 286 Enhanced Argument Tuples von Loewis
|
||||||
S 287 reStructuredText Standard Docstring Format Goodger
|
S 287 reStructuredText Docstring Format Goodger
|
||||||
I 291 Backward Compatibility for Standard Library Norwitz
|
I 291 Backward Compatibility for Standard Library Norwitz
|
||||||
S 292 Simpler String Substitutions Warsaw
|
S 292 Simpler String Substitutions Warsaw
|
||||||
S 293 Codec Error Handling Callbacks Dörwald
|
S 293 Codec Error Handling Callbacks Dörwald
|
||||||
|
|
@ -246,7 +246,7 @@ Numerical Index
|
||||||
SF 255 Simple Generators Schemenauer, et al
|
SF 255 Simple Generators Schemenauer, et al
|
||||||
S 256 Docstring Processing System Framework Goodger
|
S 256 Docstring Processing System Framework Goodger
|
||||||
S 257 Docstring Conventions Goodger, van Rossum
|
S 257 Docstring Conventions Goodger, van Rossum
|
||||||
S 258 DPS Generic Implementation Details Goodger
|
S 258 Docutils Design Specification Goodger
|
||||||
SR 259 Omit printing newline after newline van Rossum
|
SR 259 Omit printing newline after newline van Rossum
|
||||||
SF 260 Simplify xrange() van Rossum
|
SF 260 Simplify xrange() van Rossum
|
||||||
S 261 Support for "wide" Unicode characters Prescod
|
S 261 Support for "wide" Unicode characters Prescod
|
||||||
|
|
@ -275,7 +275,7 @@ Numerical Index
|
||||||
S 284 Integer for-loops Eppstein, Ewing
|
S 284 Integer for-loops Eppstein, Ewing
|
||||||
SF 285 Adding a bool type van Rossum
|
SF 285 Adding a bool type van Rossum
|
||||||
S 286 Enhanced Argument Tuples von Loewis
|
S 286 Enhanced Argument Tuples von Loewis
|
||||||
S 287 reStructuredText Standard Docstring Format Goodger
|
S 287 reStructuredText Docstring Format Goodger
|
||||||
SD 288 Generators Attributes and Exceptions Hettinger
|
SD 288 Generators Attributes and Exceptions Hettinger
|
||||||
SR 289 Generator Comprehensions Hettinger
|
SR 289 Generator Comprehensions Hettinger
|
||||||
I 290 Code Migration and Modernization Hettinger
|
I 290 Code Migration and Modernization Hettinger
|
||||||
|
|
|
||||||
368
pep-0256.txt
368
pep-0256.txt
|
|
@ -2,167 +2,154 @@ PEP: 256
|
||||||
Title: Docstring Processing System Framework
|
Title: Docstring Processing System Framework
|
||||||
Version: $Revision$
|
Version: $Revision$
|
||||||
Last-Modified: $Date$
|
Last-Modified: $Date$
|
||||||
Author: dgoodger@bigfoot.com (David Goodger)
|
Author: goodger@users.sourceforge.net (David Goodger)
|
||||||
Discussions-To: doc-sig@python.org
|
Discussions-To: doc-sig@python.org
|
||||||
Status: Draft
|
Status: Draft
|
||||||
Type: Standards Track
|
Type: Standards Track
|
||||||
Requires: PEP 257 Docstring Conventions
|
|
||||||
PEP 258 DPS Generic Implementation Details
|
|
||||||
Created: 01-Jun-2001
|
Created: 01-Jun-2001
|
||||||
Post-History:
|
Post-History: 13-Jun-2001
|
||||||
|
|
||||||
|
|
||||||
Abstract
|
Abstract
|
||||||
|
|
||||||
Python modules, classes and functions have a string attribute
|
|
||||||
called __doc__. If the first expression inside the definition is
|
|
||||||
a literal string, that string is assigned to the __doc__
|
|
||||||
attribute, called a documentation string or docstring. It is
|
|
||||||
often used to summarize the interface of the module, class or
|
|
||||||
function.
|
|
||||||
|
|
||||||
There is no standard format (markup) for docstrings, nor are there
|
|
||||||
standard tools for extracting docstrings and transforming them
|
|
||||||
into useful structured formats (e.g., HTML, DocBook, TeX). Those
|
|
||||||
tools that do exist are for the most part unmaintained and unused.
|
|
||||||
The issues surrounding docstring processing have been contentious
|
|
||||||
and difficult to resolve.
|
|
||||||
|
|
||||||
This PEP proposes a Docstring Processing System (DPS) framework.
|
|
||||||
It separates out the components (program and conceptual), enabling
|
|
||||||
the resolution of individual issues either through consensus (one
|
|
||||||
solution) or through divergence (many). It promotes standard
|
|
||||||
interfaces which will allow a variety of plug-in components (e.g.,
|
|
||||||
input parsers and output formatters) to be used.
|
|
||||||
|
|
||||||
This PEP presents the concepts of a DPS framework independently of
|
|
||||||
implementation details.
|
|
||||||
|
|
||||||
|
|
||||||
Rationale
|
|
||||||
|
|
||||||
Python lends itself to inline documentation. With its built-in
|
Python lends itself to inline documentation. With its built-in
|
||||||
docstring syntax, a limited form of Literate Programming [2] is
|
docstring syntax, a limited form of Literate Programming [1]_ is
|
||||||
easy to do in Python. However, there are no satisfactory standard
|
easy to do in Python. However, there are no satisfactory standard
|
||||||
tools for extracting and processing Python docstrings. The lack
|
tools for extracting and processing Python docstrings. The lack
|
||||||
of a standard toolset is a significant gap in Python's
|
of a standard toolset is a significant gap in Python's
|
||||||
infrastructure; this PEP aims to fill the gap.
|
infrastructure; this PEP aims to fill the gap.
|
||||||
|
|
||||||
There are standard inline documentation systems for some other
|
The issues surrounding docstring processing have been contentious
|
||||||
languages. For example, Perl has POD (plain old documentation)
|
and difficult to resolve. This PEP proposes a generic Docstring
|
||||||
and Java has Javadoc, but neither of these mesh with the Pythonic
|
Processing System (DPS) framework, which separates out the
|
||||||
way. POD is very explicit, but takes after Perl in terms of
|
components (program and conceptual), enabling the resolution of
|
||||||
readability. Javadoc is HTML-centric; except for '@field' tags,
|
individual issues either through consensus (one solution) or
|
||||||
raw HTML is used for markup. There are also general tools such as
|
through divergence (many). It promotes standard interfaces which
|
||||||
Autoduck and Web (Tangle & Weave), useful for multiple languages.
|
will allow a variety of plug-in components (input context readers,
|
||||||
|
markup parsers, and output format writers) to be used.
|
||||||
|
|
||||||
There have been many attempts to write autodocumentation systems
|
The concepts of a DPS framework are presented independently of
|
||||||
|
implementation details.
|
||||||
|
|
||||||
|
|
||||||
|
Roadmap to the Doctring PEPs
|
||||||
|
|
||||||
|
There are many aspects to docstring processing. The "Docstring
|
||||||
|
PEPs" have broken up the issues in order to deal with each of them
|
||||||
|
in isolation, or as close as possible. The individual aspects and
|
||||||
|
associated PEPs are as follows:
|
||||||
|
|
||||||
|
* Docstring syntax. PEP 287, reStructuredText Docstring Format,
|
||||||
|
proposes a syntax for Python docstrings, PEPs, and other uses.
|
||||||
|
|
||||||
|
* Docstring semantics consist of at least two aspects:
|
||||||
|
|
||||||
|
- Conventions: the high-level structure of docstrings. Dealt
|
||||||
|
with in PEP 257, Docstring Conventions.
|
||||||
|
|
||||||
|
- Methodology: rules for the informational content of
|
||||||
|
docstrings. Not addressed.
|
||||||
|
|
||||||
|
* Processing mechanisms. This PEP outlines the high-level issues
|
||||||
|
and specification of an abstract docstring processing system
|
||||||
|
(DPS). PEP 258, Docutils Design Specification, is an overview
|
||||||
|
of the design and implementation of one DPS under development.
|
||||||
|
|
||||||
|
* Output styles: developers want the documentation generated from
|
||||||
|
their source code to look good, and there are many different
|
||||||
|
ideas about what that means. PEP 258 touches on "Stylist
|
||||||
|
Transforms". This aspect of docstring processing has yet to be
|
||||||
|
fully explored.
|
||||||
|
|
||||||
|
By separating out the issues, we can form consensus more easily
|
||||||
|
(smaller fights ;-), and accept divergence more readily.
|
||||||
|
|
||||||
|
|
||||||
|
Rationale
|
||||||
|
|
||||||
|
There are standard inline documentation systems for some other
|
||||||
|
languages. For example, Perl has POD [2]_ and Java has Javadoc
|
||||||
|
[3]_, but neither of these mesh with the Pythonic way. POD syntax
|
||||||
|
is very explicit, but takes after Perl in terms of readability.
|
||||||
|
Javadoc is HTML-centric; except for '@field' tags, raw HTML is
|
||||||
|
used for markup. There are also general tools such as Autoduck
|
||||||
|
[4]_ and Web (Tangle & Weave) [5]_, useful for multiple languages.
|
||||||
|
|
||||||
|
There have been many attempts to write auto-documentation systems
|
||||||
for Python (not an exhaustive list):
|
for Python (not an exhaustive list):
|
||||||
|
|
||||||
- Marc-Andre Lemburg's doc.py [3]
|
- Marc-Andre Lemburg's doc.py [6]_
|
||||||
|
|
||||||
- Daniel Larsson's pythondoc & gendoc [4]
|
- Daniel Larsson's pythondoc & gendoc [7]_
|
||||||
|
|
||||||
- Doug Hellmann's HappyDoc [5]
|
- Doug Hellmann's HappyDoc [8]_
|
||||||
|
|
||||||
- Laurence Tratt's Crystal [6]
|
- Laurence Tratt's Crystal [9]_
|
||||||
|
|
||||||
- Ka-Ping Yee's htmldoc & pydoc [7] (pydoc.py is now part of the Python
|
- Ka-Ping Yee's htmldoc & pydoc [10]_ (pydoc.py is now part of the
|
||||||
standard library; see below)
|
Python standard library; see below)
|
||||||
|
|
||||||
- Tony Ibbs' docutils [8]
|
- Tony Ibbs' docutils [11]_
|
||||||
|
|
||||||
|
- Edward Loper's STminus formalization and related efforts [12]_
|
||||||
|
|
||||||
These systems, each with different goals, have had varying degrees
|
These systems, each with different goals, have had varying degrees
|
||||||
of success. A problem with many of the above systems was
|
of success. A problem with many of the above systems was
|
||||||
over-ambition. They provided a self-contained set of components: a
|
over-ambition combined with inflexibility. They provided a
|
||||||
docstring extraction system, an input parser, an internal
|
self-contained set of components: a docstring extraction system, a
|
||||||
processing system and one or more output formatters. Inevitably,
|
markup parser, an internal processing system and one or more
|
||||||
one or more components had serious shortcomings, preventing the
|
output format writers with a fixed style. Inevitably, one or more
|
||||||
system from being adopted as a standard tool.
|
aspects of each system had serious shortcomings, and they were not
|
||||||
|
easily extended or modified, preventing them from being adopted as
|
||||||
Throughout the existence of the Python Documentation Special
|
standard tools.
|
||||||
Interest Group (Doc-SIG) [9], consensus on a single standard
|
|
||||||
docstring format has never been reached. A lightweight, implicit
|
|
||||||
markup has been sought, for the following reasons (among others):
|
|
||||||
|
|
||||||
1. 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.
|
|
||||||
|
|
||||||
2. Programmers want to add structure to their docstrings, without
|
|
||||||
sacrificing raw docstring readability. Unadorned plaintext
|
|
||||||
cannot be transformed ('up-translated') into useful structured
|
|
||||||
formats.
|
|
||||||
|
|
||||||
3. Explicit markup (like XML or TeX) has been widely considered
|
|
||||||
unreadable by the uninitiated.
|
|
||||||
|
|
||||||
4. Implicit markup is aesthetically compatible with the clean and
|
|
||||||
minimalist Python syntax.
|
|
||||||
|
|
||||||
Early on, variants of Setext (Structure Enhanced Text) [10],
|
|
||||||
including Digital Creation's StructuredText [11], were proposed
|
|
||||||
for Python docstring formatting. Hereafter we will collectively
|
|
||||||
call these variants 'STexts'. Although used by some (including in
|
|
||||||
most of the above-listed autodocumentation tools), these markup
|
|
||||||
schemes have failed to become standard because:
|
|
||||||
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
- STexts have been sometimes surprising: bits of text are marked
|
|
||||||
up unexpectedly, leading to user frustration.
|
|
||||||
|
|
||||||
- SText implementations have been buggy.
|
|
||||||
|
|
||||||
- Some STexts have have had no formal specification except for the
|
|
||||||
implementation itself. A buggy implementation meant a buggy
|
|
||||||
spec, and vice-versa.
|
|
||||||
|
|
||||||
- There has been no mechanism to get around the SText markup rules
|
|
||||||
when a markup character is used in a non-markup context.
|
|
||||||
|
|
||||||
Recognizing the deficiencies of STexts, some people have proposed
|
|
||||||
using explicit markup of some kind. There have been proposals for
|
|
||||||
using XML, HTML, TeX, POD, and Javadoc at one time or another.
|
|
||||||
Proponents of STexts have vigorously opposed these proposals, and
|
|
||||||
the debates have continued off and on for at least five years.
|
|
||||||
|
|
||||||
It has become clear (to this author, at least) that the "all or
|
It has become clear (to this author, at least) that the "all or
|
||||||
nothing" approach cannot succeed, since no all-encompassing
|
nothing" approach cannot succeed, since no monolithic
|
||||||
proposal could possibly be agreed upon by all interested parties.
|
self-contained system could possibly be agreed upon by all
|
||||||
A modular component approach, where components may be multiply
|
interested parties. A modular component approach designed for
|
||||||
implemented, is the only chance at success. By separating out the
|
extension, where components may be multiply implemented, may be
|
||||||
issues, we can form consensus more easily (smaller fights ;-), and
|
the only chance for success. Standard inter-component APIs will
|
||||||
accept divergence more readily.
|
make the DPS components comprehensible without requiring detailed
|
||||||
|
knowledge of the whole, lowering the barrier for contributions,
|
||||||
|
and ultimately resulting in a rich and varied system.
|
||||||
|
|
||||||
Each of the components of a docstring processing system should be
|
Each of the components of a docstring processing system should be
|
||||||
developed independently. A 'best of breed' system should be
|
developed independently. A 'best of breed' system should be
|
||||||
chosen and/or developed and eventually included in Python's
|
chosen, either merged from existing systems, and/or developed
|
||||||
standard library.
|
anew. This system should be included in Python's standard
|
||||||
|
library.
|
||||||
|
|
||||||
|
|
||||||
Pydoc & Other Existing Systems
|
PyDoc & Other Existing Systems
|
||||||
|
|
||||||
Pydoc is part of the Python 2.1 standard library. It extracts and
|
PyDoc became part of the Python standard library as of release
|
||||||
displays docstrings from within the Python interactive
|
2.1. It extracts and displays docstrings from within the Python
|
||||||
interpreter, from the shell command line, and from a GUI window
|
interactive interpreter, from the shell command line, and from a
|
||||||
into a web browser (HTML). In the case of GUI/HTML, except for
|
GUI window into a web browser (HTML). Although a very useful
|
||||||
some heuristic hyperlinking of identifier names, no formatting of
|
tool, PyDoc has several deficiencies, including:
|
||||||
the docstrings is done. They are presented within <p><small><tt>
|
|
||||||
tags to avoid unwanted line wrapping. Unfortunately, the result
|
- In the case of the GUI/HTML, except for some heuristic
|
||||||
is not pretty.
|
hyperlinking of identifier names, no formatting of the
|
||||||
|
docstrings is done. They are presented within <p><small><tt>
|
||||||
|
tags to avoid unwanted line wrapping. Unfortunately, the result
|
||||||
|
is not attractive.
|
||||||
|
|
||||||
|
- PyDoc extracts docstrings and structural information (class
|
||||||
|
identifiers, method signatures, etc.) from imported module
|
||||||
|
objects. There are security issues involved with importing
|
||||||
|
untrusted code. Also, information from the source is lost when
|
||||||
|
importing, such as comments, "additional docstrings" (string
|
||||||
|
literals in non-docstring contexts; see PEP 258 [13]_), and the
|
||||||
|
order of definitions.
|
||||||
|
|
||||||
The functionality proposed in this PEP could be added to or used
|
The functionality proposed in this PEP could be added to or used
|
||||||
by pydoc when serving HTML pages. However, the proposed docstring
|
by PyDoc when serving HTML pages. The proposed docstring
|
||||||
processing system's functionality is much more than pydoc needs
|
processing system's functionality is much more than PyDoc needs in
|
||||||
(in its current form). Either an independent tool will be
|
its current form. Either an independent tool will be developed
|
||||||
developed (which pydoc may or may not use), or pydoc could be
|
(which PyDoc may or may not use), or PyDoc could be expanded to
|
||||||
expanded to encompass this functionality and *become* the
|
encompass this functionality and *become* the docstring processing
|
||||||
docstring processing system (or one such system). That decision
|
system (or one such system). That decision is beyond the scope of
|
||||||
is beyond the scope of this PEP.
|
this PEP.
|
||||||
|
|
||||||
Similarly for other existing docstring processing systems, their
|
Similarly for other existing docstring processing systems, their
|
||||||
authors may or may not choose compatibility with this framework.
|
authors may or may not choose compatibility with this framework.
|
||||||
|
|
@ -182,115 +169,106 @@ Specification
|
||||||
|
|
||||||
- First line is a one-line synopsis.
|
- First line is a one-line synopsis.
|
||||||
|
|
||||||
PEP 257, Docstring Conventions[12], documents these issues.
|
PEP 257, Docstring Conventions [14]_, documents some of these
|
||||||
|
issues.
|
||||||
|
|
||||||
2. Docstring processing system generic implementation details.
|
2. Docstring processing system design specification. Documents
|
||||||
Documents issues such as:
|
issues such as:
|
||||||
|
|
||||||
- High-level spec: what a DPS does.
|
- High-level spec: what a DPS does.
|
||||||
|
|
||||||
- Command-line interface for executable script.
|
- Command-line interface for executable script.
|
||||||
|
|
||||||
- System Python API
|
- System Python API.
|
||||||
|
|
||||||
- Docstring extraction rules.
|
- Docstring extraction rules.
|
||||||
|
|
||||||
- Input parser API.
|
- Readers, which encapsulate the input context .
|
||||||
|
|
||||||
- Intermediate internal data structure: output from input parser,
|
- Parsers.
|
||||||
input to output formatter.
|
|
||||||
|
|
||||||
- Output formatter API.
|
- Document tree: the intermediate internal data structure. The
|
||||||
|
output of the Parser and Reader, and the input to the Writer
|
||||||
|
all share the same data structure.
|
||||||
|
|
||||||
- Output management.
|
- Transforms, which modify the document tree.
|
||||||
|
|
||||||
|
- Writers for output formats.
|
||||||
|
|
||||||
|
- Distributors, which handle output management (one file, many
|
||||||
|
files, or objects in memory).
|
||||||
|
|
||||||
These issues are applicable to any docstring processing system
|
These issues are applicable to any docstring processing system
|
||||||
implementation. PEP 258, DPS Generic Implementation
|
implementation. PEP 258, Docutils Design Specification [13 ]_,
|
||||||
Details[13], documents these issues.
|
documents these issues.
|
||||||
|
|
||||||
3. Docstring processing system implementation.
|
3. Docstring processing system implementation.
|
||||||
|
|
||||||
4. Input markup specifications: docstring syntax.
|
4. Input markup specifications: docstring syntax. PEP 287,
|
||||||
|
reStructuredText Docstring Format [15]_, proposes a standard
|
||||||
|
syntax.
|
||||||
|
|
||||||
5. Input parser implementations.
|
5. Input parser implementations.
|
||||||
|
|
||||||
6. Output formats (HTML, XML, TeX, DocBook, info, etc.).
|
6. Input context readers ("modes": Python source code, PEP,
|
||||||
|
standalone text file, email, etc.) and implementations.
|
||||||
|
|
||||||
7. Output formatter implementations.
|
7. Stylists: certain input context readers may have associated
|
||||||
|
stylists which allow for a variety of output document styles.
|
||||||
|
|
||||||
Components 1, 2, and 3 will be the subject of individual companion
|
8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
|
||||||
PEPs, although they may be merged into this PEP once consensus is
|
implementations.
|
||||||
reached. If there is only one implementation, PEPs for components
|
|
||||||
2 & 3 can be combined. Multiple PEPs will be necessary for each
|
|
||||||
of components 4, 5, 6, and 7. An alternative to the PEP mechanism
|
|
||||||
may be used instead, since these are not directly related to the
|
|
||||||
Python language.
|
|
||||||
|
|
||||||
The following diagram shows an overview of the framework.
|
Components 1, 2/3, and 4/5 are the subject of individual companion
|
||||||
Interfaces are indicated by double-borders. The ASCII diagram is
|
PEPs. If there is another implementation of the framework or
|
||||||
very wide; please turn off line wrapping to view it:
|
syntax/parser, additional PEPs may be required. Multiple
|
||||||
|
implementations of each of components 6 and 7 will be required;
|
||||||
|
the PEP mechanism may be overkill for these components.
|
||||||
+========================+
|
|
||||||
| Command-Line Interface |
|
|
||||||
+========================+
|
|
||||||
| Executable Script |
|
|
||||||
+------------------------+
|
|
||||||
|
|
|
||||||
| calls
|
|
||||||
v
|
|
||||||
+===========================================+ returns +---------+
|
|
||||||
| System Python API |==========>| output |
|
|
||||||
+--------+ +===========================================+ | objects |
|
|
||||||
_ writes | Python | reads | Docstring Processing System | +---------+
|
|
||||||
/ \ ==============>| module |<===========| |
|
|
||||||
\_/ +--------+ | input | transformation, | output | +--------+
|
|
||||||
| +-------------+ follows | docstring | integration, | object | writes | output |
|
|
||||||
--+-- consults | docstring |<-----------| extraction | linking | management |===========>| files |
|
|
||||||
| --------->| conventions | +============+=====+=====+=====+============+ +--------+
|
|
||||||
/ \ +-------------+ | parser API | | formatter API |
|
|
||||||
/ \ +-------------+ +===========+======+ +======+===========+ +--------+
|
|
||||||
author consults | markup | implements | input | intermediate | output | implements | output |
|
|
||||||
--------->| syntax spec |<-----------| parser | data structure | formatter |----------->| format |
|
|
||||||
+-------------+ +-----------+-------------------+-----------+ +--------+
|
|
||||||
|
|
||||||
|
|
||||||
Project Web Site
|
Project Web Site
|
||||||
|
|
||||||
A SourceForge project has been set up for this work at
|
A SourceForge project has been set up for this work at
|
||||||
http://docstring.sf.net.
|
http://docutils.sourceforge.net/.
|
||||||
|
|
||||||
|
|
||||||
References and Footnotes
|
References and Footnotes
|
||||||
|
|
||||||
[1] PEP 236, Docstring Format, Zadka
|
[1] http://www.literateprogramming.com/
|
||||||
http://www.python.org/peps/pep-0216.html
|
|
||||||
|
|
||||||
[2] http://www.literateprogramming.com/
|
[2] Perl "Plain Old Documentation"
|
||||||
|
http://www.perldoc.com/perl5.6/pod/perlpod.html
|
||||||
|
|
||||||
[3] http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
|
[3] http://java.sun.com/j2se/javadoc/
|
||||||
|
|
||||||
[4] http://starship.python.net/crew/danilo/pythondoc/
|
[4] http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
|
||||||
|
|
||||||
[5] http://happydoc.sf.net/
|
[5] http://www-cs-faculty.stanford.edu/~knuth/cweb.html
|
||||||
|
|
||||||
[6] http://www.btinternet.com/~tratt/comp/python/crystal/index.html
|
[6] http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
|
||||||
|
|
||||||
[7] http://www.lfw.org/python/
|
[7] http://starship.python.net/crew/danilo/pythondoc/
|
||||||
|
|
||||||
[8] http://homepage.ntlworld.com/tibsnjoan/docutils/
|
[8] http://happydoc.sourceforge.net/
|
||||||
|
|
||||||
[9] http://www.python.org/sigs/doc-sig/
|
[9] http://www.btinternet.com/~tratt/comp/python/crystal/
|
||||||
|
|
||||||
[10] http://www.bsdi.com/setext/
|
[10] http://www.python.org/doc/current/lib/module-pydoc.html
|
||||||
|
|
||||||
[11] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
|
[11] http://homepage.ntlworld.com/tibsnjoan/docutils/
|
||||||
|
|
||||||
[12] PEP 257, Docstring Conventions, Goodger, Van Rossum
|
[12] http://www.cis.upenn.edu/~edloper/pydoc/
|
||||||
|
|
||||||
|
[13] PEP 258, Docutils Design Specification, Goodger
|
||||||
|
http://www.python.org/peps/pep-0258.html
|
||||||
|
|
||||||
|
[14] PEP 257, Docstring Conventions, Goodger, Van Rossum
|
||||||
http://www.python.org/peps/pep-0257.html
|
http://www.python.org/peps/pep-0257.html
|
||||||
|
|
||||||
[13] PEP 258, DPS Generic Implementation Details, Goodger
|
[15] PEP 287, reStructuredText Docstring Format, Goodger
|
||||||
http://www.python.org/peps/pep-0258.html
|
http://www.python.org/peps/pep-0287.html
|
||||||
|
|
||||||
|
[16] http://www.python.org/sigs/doc-sig/
|
||||||
|
|
||||||
|
|
||||||
Copyright
|
Copyright
|
||||||
|
|
@ -300,16 +278,14 @@ Copyright
|
||||||
|
|
||||||
Acknowledgements
|
Acknowledgements
|
||||||
|
|
||||||
This document borrows text from PEP 216, Docstring Format by Moshe
|
This document borrows ideas from the archives of the Python
|
||||||
Zadka[1]. It is intended as a reorganization of PEP 216 and its
|
Doc-SIG [16]_. Thanks to all members past & present.
|
||||||
approach.
|
|
||||||
|
|
||||||
This document also borrows ideas from the archives of the Python
|
|
||||||
Doc-SIG. Thanks to all members past & present.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Local Variables:
|
Local Variables:
|
||||||
mode: indented-text
|
mode: indented-text
|
||||||
indent-tabs-mode: nil
|
indent-tabs-mode: nil
|
||||||
|
fill-column: 70
|
||||||
|
sentence-end-double-space: t
|
||||||
End:
|
End:
|
||||||
|
|
|
||||||
85
pep-0257.txt
85
pep-0257.txt
|
|
@ -2,10 +2,10 @@ PEP: 257
|
||||||
Title: Docstring Conventions
|
Title: Docstring Conventions
|
||||||
Version: $Revision$
|
Version: $Revision$
|
||||||
Last-Modified: $Date$
|
Last-Modified: $Date$
|
||||||
Author: dgoodger@bigfoot.com (David Goodger),
|
Author: goodger@users.sourceforge.net (David Goodger),
|
||||||
guido@digicool.com (Guido van Rossum)
|
guido@python.org (Guido van Rossum)
|
||||||
Discussions-To: doc-sig@python.org
|
Discussions-To: doc-sig@python.org
|
||||||
Status: Draft
|
Status: Active
|
||||||
Type: Informational
|
Type: Informational
|
||||||
Created: 29-May-2001
|
Created: 29-May-2001
|
||||||
Post-History: 13-Jun-2001
|
Post-History: 13-Jun-2001
|
||||||
|
|
@ -32,9 +32,9 @@ Rationale
|
||||||
--Tim Peters on comp.lang.python, 2001-06-16
|
--Tim Peters on comp.lang.python, 2001-06-16
|
||||||
|
|
||||||
If you violate the conventions, the worst you'll get is some dirty
|
If you violate the conventions, the worst you'll get is some dirty
|
||||||
looks. But some software (such as the Docstring Processing System
|
looks. But some software (such as the Docutils docstring
|
||||||
[1]) will be aware of the conventions, so following them will get
|
processing system [1] [2]) will be aware of the conventions, so
|
||||||
you the best results.
|
following them will get you the best results.
|
||||||
|
|
||||||
|
|
||||||
Specification
|
Specification
|
||||||
|
|
@ -43,7 +43,7 @@ Specification
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
A docstring is a string literal that occurs as the first statement
|
A docstring is a string literal that occurs as the first statement
|
||||||
in a module, function, class, or method definition. Such a
|
in a module, function, class, or method definition. Such a
|
||||||
docstring becomes the __doc__ special attribute of that object.
|
docstring becomes the __doc__ special attribute of that object.
|
||||||
|
|
||||||
All modules should normally have docstrings, and all functions and
|
All modules should normally have docstrings, and all functions and
|
||||||
|
|
@ -52,25 +52,28 @@ Specification
|
||||||
docstrings. A package may be documented in the module docstring
|
docstrings. A package may be documented in the module docstring
|
||||||
of the __init__.py file in the package directory.
|
of the __init__.py file in the package directory.
|
||||||
|
|
||||||
String literals occuring elsewhere in Python code may also act as
|
String literals occurring elsewhere in Python code may also act as
|
||||||
documentation. They are not recognized by the Python bytecode
|
documentation. They are not recognized by the Python bytecode
|
||||||
compiler and are not accessible as runtime object attributes
|
compiler and are not accessible as runtime object attributes
|
||||||
(i.e. not assigned to __doc__), but two types of extra docstrings
|
(i.e. not assigned to __doc__), but two types of extra docstrings
|
||||||
are recognized by software tools:
|
may be extracted by software tools:
|
||||||
|
|
||||||
1. String literals occuring immediately after a simple assignment
|
1. String literals occurring immediately after a simple assignment
|
||||||
at the top level of a module, class, or __init__ method
|
at the top level of a module, class, or __init__ method
|
||||||
are called "attribute docstrings".
|
are called "attribute docstrings".
|
||||||
|
|
||||||
2. String literals occuring immediately after another docstring
|
2. String literals occurring immediately after another docstring
|
||||||
are called "additional docstrings".
|
are called "additional docstrings".
|
||||||
|
|
||||||
Please see PEP 258 "DPS Generic Implementation Details" [2] for a
|
Please see PEP 258 "Docutils Design Specification" [2] for a
|
||||||
detailed description of attribute and additional docstrings.
|
detailed description of attribute and additional docstrings.
|
||||||
|
|
||||||
|
XXX Mention docstrings of 2.2 properties.
|
||||||
|
|
||||||
For consistency, always use """triple double quotes""" around
|
For consistency, always use """triple double quotes""" around
|
||||||
docstrings. Use r"""raw triple double quotes""" if you use any
|
docstrings. Use r"""raw triple double quotes""" if you use any
|
||||||
backslashes in your docstrings.
|
backslashes in your docstrings. For Unicode docstrings, use
|
||||||
|
u"""Unicode triple-quoted strings""".
|
||||||
|
|
||||||
There are two forms of docstrings: one-liners and multi-line
|
There are two forms of docstrings: one-liners and multi-line
|
||||||
docstrings.
|
docstrings.
|
||||||
|
|
@ -87,7 +90,7 @@ Specification
|
||||||
if _kos_root: return _kos_root
|
if _kos_root: return _kos_root
|
||||||
...
|
...
|
||||||
|
|
||||||
Notes:
|
Notes:
|
||||||
|
|
||||||
- Triple quotes are used even though the string fits on one line.
|
- Triple quotes are used even though the string fits on one line.
|
||||||
This makes it easy to later expand it.
|
This makes it easy to later expand it.
|
||||||
|
|
@ -98,18 +101,27 @@ Specification
|
||||||
- There's no blank line either before or after the docstring.
|
- There's no blank line either before or after the docstring.
|
||||||
|
|
||||||
- The docstring is a phrase ending in a period. It prescribes the
|
- The docstring is a phrase ending in a period. It prescribes the
|
||||||
function's effect as a command ("Do this", "Return that"), not
|
function or method's effect as a command ("Do this", "Return
|
||||||
as a description: e.g. don't write "Returns the pathname ..."
|
that"), not as a description: e.g. don't write "Returns the
|
||||||
|
pathname ..."
|
||||||
|
|
||||||
- The one-line docstring should NOT be a "signature" reiterating
|
- The one-line docstring should NOT be a "signature" reiterating
|
||||||
the function parameters (which can be obtained by
|
the function/method parameters (which can be obtained by
|
||||||
introspection). Don't do::
|
introspection). Don't do::
|
||||||
|
|
||||||
def function(a, b):
|
def function(a, b):
|
||||||
"""function(a, b) -> list"""
|
"""function(a, b) -> list"""
|
||||||
|
|
||||||
This type of docstring is only appropriate for C functions (such
|
This type of docstring is only appropriate for C functions (such
|
||||||
as built-ins), where introspection is not possible.
|
as built-ins), where introspection is not possible. However,
|
||||||
|
the nature of the *return value* cannot be determined by
|
||||||
|
introspection, so it should be mentioned. The preferred form
|
||||||
|
for such a docstring would be something like::
|
||||||
|
|
||||||
|
def function(a, b):
|
||||||
|
"""Do X and return a list."""
|
||||||
|
|
||||||
|
(Of course "Do X" should be replaced by a useful description!)
|
||||||
|
|
||||||
Multi-line Docstrings
|
Multi-line Docstrings
|
||||||
----------------------
|
----------------------
|
||||||
|
|
@ -118,7 +130,9 @@ Specification
|
||||||
one-line docstring, followed by a blank line, followed by a more
|
one-line docstring, followed by a blank line, followed by a more
|
||||||
elaborate description. The summary line may be used by automatic
|
elaborate description. The summary line may be used by automatic
|
||||||
indexing tools; it is important that it fits on one line and is
|
indexing tools; it is important that it fits on one line and is
|
||||||
separated from the rest of the docstring by a blank line.
|
separated from the rest of the docstring by a blank line. The
|
||||||
|
summary line may be on the same line as the opening quotes or on
|
||||||
|
the next line.
|
||||||
|
|
||||||
The entire docstring is indented the same as the quotes at its
|
The entire docstring is indented the same as the quotes at its
|
||||||
first line (see example below). Docstring processing tools will
|
first line (see example below). Docstring processing tools will
|
||||||
|
|
@ -132,11 +146,11 @@ Specification
|
||||||
class's methods are separated from each other by a single blank
|
class's methods are separated from each other by a single blank
|
||||||
line, and the docstring needs to be offset from the first method
|
line, and the docstring needs to be offset from the first method
|
||||||
by a blank line; for symmetry, put a blank line between the class
|
by a blank line; for symmetry, put a blank line between the class
|
||||||
header and the docstring. Docstrings documenting functions
|
header and the docstring. Docstrings documenting functions or
|
||||||
generally don't have this requirement, unless the function's body
|
methods generally don't have this requirement, unless the function
|
||||||
is written as a number of blank-line separated sections -- in this
|
or method's body is written as a number of blank-line separated
|
||||||
case, treat the docstring as another section, and precede it with
|
sections -- in this case, treat the docstring as another section,
|
||||||
a blank line.
|
and precede it with a blank line.
|
||||||
|
|
||||||
The docstring of a script (a stand-alone program) should be usable
|
The docstring of a script (a stand-alone program) should be usable
|
||||||
as its "usage" message, printed when the script is invoked with
|
as its "usage" message, printed when the script is invoked with
|
||||||
|
|
@ -152,7 +166,7 @@ Specification
|
||||||
exceptions and functions (and any other objects) that are exported
|
exceptions and functions (and any other objects) that are exported
|
||||||
by the module, with a one-line summary of each. (These summaries
|
by the module, with a one-line summary of each. (These summaries
|
||||||
generally give less detail than the summary line in the object's
|
generally give less detail than the summary line in the object's
|
||||||
docstring.) The docstring for a package (i.e., the docstring of
|
docstring.) The docstring for a package (i.e., the docstring of
|
||||||
the package's __init__.py module) should also list the modules and
|
the package's __init__.py module) should also list the modules and
|
||||||
subpackages exported by the package.
|
subpackages exported by the package.
|
||||||
|
|
||||||
|
|
@ -183,16 +197,16 @@ Specification
|
||||||
functions or methods in upper case in running text. Python is
|
functions or methods in upper case in running text. Python is
|
||||||
case sensitive and the argument names can be used for keyword
|
case sensitive and the argument names can be used for keyword
|
||||||
arguments, so the docstring should document the correct argument
|
arguments, so the docstring should document the correct argument
|
||||||
names. It is best to list each argument on a separate line. For
|
names. It is best to list each argument on a separate line. For
|
||||||
example::
|
example::
|
||||||
|
|
||||||
def complex(real=0.0, imag=0.0):
|
def complex(real=0.0, imag=0.0):
|
||||||
"""Form a complex number.
|
"""Form a complex number.
|
||||||
|
|
||||||
Keyword arguments:
|
Keyword arguments:
|
||||||
real -- the real part (default 0.0)
|
real -- the real part (default 0.0)
|
||||||
imag -- the imaginary part (default 0.0)
|
imag -- the imaginary part (default 0.0)
|
||||||
|
|
||||||
"""
|
"""
|
||||||
if imag == 0.0 and real == 0.0: return complex_zero
|
if imag == 0.0 and real == 0.0: return complex_zero
|
||||||
...
|
...
|
||||||
|
|
@ -208,14 +222,13 @@ References and Footnotes
|
||||||
[1] PEP 256, Docstring Processing System Framework, Goodger
|
[1] PEP 256, Docstring Processing System Framework, Goodger
|
||||||
http://www.python.org/peps/pep-0256.html
|
http://www.python.org/peps/pep-0256.html
|
||||||
|
|
||||||
[2] PEP 258, DPS Generic Implementation Details, Goodger
|
[2] PEP 258, Docutils Design Specification, Goodger
|
||||||
http://www.python.org/peps/pep-0258.html
|
http://www.python.org/peps/pep-0258.html
|
||||||
|
|
||||||
[3] Guido van Rossum, Python's creator and Benevolent Dictator For
|
[3] Guido van Rossum, Python's creator and Benevolent Dictator For
|
||||||
Life.
|
Life.
|
||||||
|
|
||||||
[4] PEP 8, Style Guide for Python Code, van Rossum, Warsaw
|
[4] http://www.python.org/doc/essays/styleguide.html
|
||||||
http://www.python.org/peps/pep-0008.html
|
|
||||||
|
|
||||||
[5] http://www.python.org/sigs/doc-sig/
|
[5] http://www.python.org/sigs/doc-sig/
|
||||||
|
|
||||||
|
|
@ -228,7 +241,7 @@ Copyright
|
||||||
Acknowledgements
|
Acknowledgements
|
||||||
|
|
||||||
The "Specification" text comes mostly verbatim from the Python
|
The "Specification" text comes mostly verbatim from the Python
|
||||||
Style Guide by Guido van Rossum [4].
|
Style Guide essay by Guido van Rossum [4].
|
||||||
|
|
||||||
This document borrows ideas from the archives of the Python
|
This document borrows ideas from the archives of the Python
|
||||||
Doc-SIG [5]. Thanks to all members past and present.
|
Doc-SIG [5]. Thanks to all members past and present.
|
||||||
|
|
@ -238,4 +251,6 @@ Acknowledgements
|
||||||
Local Variables:
|
Local Variables:
|
||||||
mode: indented-text
|
mode: indented-text
|
||||||
indent-tabs-mode: nil
|
indent-tabs-mode: nil
|
||||||
|
fill-column: 70
|
||||||
|
sentence-end-double-space: t
|
||||||
End:
|
End:
|
||||||
|
|
|
||||||
922
pep-0258.txt
922
pep-0258.txt
File diff suppressed because it is too large
Load Diff
482
pep-0287.txt
482
pep-0287.txt
|
|
@ -1,5 +1,5 @@
|
||||||
PEP: 287
|
PEP: 287
|
||||||
Title: reStructuredText Standard Docstring Format
|
Title: reStructuredText Docstring Format
|
||||||
Version: $Revision$
|
Version: $Revision$
|
||||||
Last-Modified: $Date$
|
Last-Modified: $Date$
|
||||||
Author: goodger@users.sourceforge.net (David Goodger)
|
Author: goodger@users.sourceforge.net (David Goodger)
|
||||||
|
|
@ -7,33 +7,86 @@ Discussions-To: doc-sig@python.org
|
||||||
Status: Draft
|
Status: Draft
|
||||||
Type: Informational
|
Type: Informational
|
||||||
Created: 25-Mar-2002
|
Created: 25-Mar-2002
|
||||||
Post-History:
|
Post-History: 02-Apr-2002
|
||||||
Replaces: 216
|
Replaces: 216
|
||||||
|
|
||||||
|
|
||||||
Abstract
|
Abstract
|
||||||
|
|
||||||
This PEP proposes that the reStructuredText [1]_ markup be adopted
|
When plaintext hasn't been expressive enough for inline
|
||||||
as the standard markup format for plaintext documentation in
|
documentation, Python programmers have sought out a format for
|
||||||
Python docstrings, and (optionally) for PEPs and ancillary
|
docstrings. This PEP proposes that the reStructuredText markup
|
||||||
documents as well. reStructuredText is a rich and extensible yet
|
[1]_ be adopted as a standard markup format for structured
|
||||||
easy-to-read, what-you-see-is-what-you-get plaintext markup
|
plaintext documentation in Python docstrings, and for PEPs and
|
||||||
syntax.
|
ancillary documents as well. reStructuredText is a rich and
|
||||||
|
extensible yet easy-to-read, what-you-see-is-what-you-get
|
||||||
|
plaintext markup syntax.
|
||||||
|
|
||||||
Only the low-level syntax of docstrings is addressed here. This
|
Only the low-level syntax of docstrings is addressed here. This
|
||||||
PEP is not concerned with docstring semantics or processing at
|
PEP is not concerned with docstring semantics or processing at all
|
||||||
all.
|
(see PEP 256 for a "Roadmap to the Doctring 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.
|
||||||
|
|
||||||
|
|
||||||
|
Benefits
|
||||||
|
|
||||||
|
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 (Doc-SIG) [2]_ 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.
|
||||||
|
|
||||||
|
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., ``*emphasis*``), 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.
|
||||||
|
|
||||||
|
The reStructuredText parser is available now. The Docutils
|
||||||
|
project is at the point where standalone reStructuredText
|
||||||
|
documents can be converted to HTML; other output format writers
|
||||||
|
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.
|
||||||
|
|
||||||
|
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".
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
Goals
|
Goals
|
||||||
|
|
||||||
These are the generally accepted goals for a docstring format, as
|
These are the generally accepted goals for a docstring format, as
|
||||||
discussed in the Python Documentation Special Interest Group
|
discussed in the Doc-SIG:
|
||||||
(Doc-SIG) [2]_:
|
|
||||||
|
|
||||||
1. It must be easy to type with any standard text editor.
|
1. It must be readable in source form by the casual observer.
|
||||||
|
|
||||||
2. It must be readable to the casual observer.
|
2. It must be easy to type with any standard text editor.
|
||||||
|
|
||||||
3. It must not need to contain information which can be deduced
|
3. It must not need to contain information which can be deduced
|
||||||
from parsing the module.
|
from parsing the module.
|
||||||
|
|
@ -44,21 +97,24 @@ Goals
|
||||||
5. It must be possible to write a module's entire documentation in
|
5. It must be possible to write a module's entire documentation in
|
||||||
docstrings, without feeling hampered by the markup language.
|
docstrings, without feeling hampered by the markup language.
|
||||||
|
|
||||||
[[Are these in fact the goals of the Doc-SIG members? Anything to
|
|
||||||
add?]]
|
|
||||||
|
|
||||||
reStructuredText meets and exceeds all of these goals, and sets
|
reStructuredText meets and exceeds all of these goals, and sets
|
||||||
its own goals as well, even more stringent. See "Features" below.
|
its own goals as well, even more stringent. See
|
||||||
|
"Docstring-Significant Features" below.
|
||||||
|
|
||||||
The goals of this PEP are as follows:
|
The goals of this PEP are as follows:
|
||||||
|
|
||||||
1. To establish a standard docstring format by attaining
|
1. To establish reStructuredText as a standard structured
|
||||||
"accepted" status (Python community consensus; BDFL
|
plaintext format for docstrings (inline documentation of Python
|
||||||
pronouncement). Once reStructuredText is a Python standard,
|
modules and packages), PEPs, README-type files and other
|
||||||
all effort can be focused on tools instead of arguing for a
|
standalone documents. "Accepted" status will be sought through
|
||||||
standard. Python needs a standard set of documentation tools.
|
Python community consensus and eventual BDFL pronouncement.
|
||||||
|
|
||||||
2. To address any related concerns raised by the Python community.
|
Please note that reStructuredText is being proposed as *a*
|
||||||
|
standard, not *the only* standard. Its use will be entirely
|
||||||
|
optional. Those who don't want to use it need not.
|
||||||
|
|
||||||
|
2. To solicit and address any related concerns raised by the
|
||||||
|
Python community.
|
||||||
|
|
||||||
3. To encourage community support. As long as multiple competing
|
3. To encourage community support. As long as multiple competing
|
||||||
markups are out there, the development community remains
|
markups are out there, the development community remains
|
||||||
|
|
@ -69,48 +125,40 @@ Goals
|
||||||
projects. It is hoped that interested developers will join
|
projects. It is hoped that interested developers will join
|
||||||
forces and work on a joint/merged/common implementation.
|
forces and work on a joint/merged/common implementation.
|
||||||
|
|
||||||
5. (Optional.) To adopt reStructuredText as the standard markup
|
Once reStructuredText is a Python standard, effort can be focused
|
||||||
for PEPs. One or both of the following strategies may be
|
on tools instead of arguing for a standard. Python needs a
|
||||||
applied:
|
standard set of documentation tools.
|
||||||
|
|
||||||
a) Keep the existing PEP section structure constructs (one-line
|
With regard to PEPs, one or both of the following strategies may
|
||||||
section headers, indented body text). Subsections can
|
be applied:
|
||||||
either be forbidden or supported with underlined headers in
|
|
||||||
the indented body text.
|
|
||||||
|
|
||||||
b) Replace the PEP section structure constructs with the
|
a) Keep the existing PEP section structure constructs (one-line
|
||||||
reStructuredText syntax. Section headers will require
|
section headers, indented body text). Subsections can either
|
||||||
underlines, subsections will be supported out of the box,
|
be forbidden, or supported with reStructuredText-style
|
||||||
and body text need not be indented (except for block
|
underlined headers in the indented body text.
|
||||||
quotes).
|
|
||||||
|
|
||||||
Support for RFC 2822 headers will be added to the
|
b) Replace the PEP section structure constructs with the
|
||||||
reStructuredText parser (unambiguous given a specific context:
|
reStructuredText syntax. Section headers will require
|
||||||
the first contiguous block of a PEP document). It may be
|
underlines, subsections will be supported out of the box,
|
||||||
desired to concretely specify what over/underline styles are
|
and body text need not be indented (except for block
|
||||||
allowed for PEP section headers, for uniformity.
|
quotes).
|
||||||
|
|
||||||
6. (Optional.) To adopt reStructuredText as the standard markup
|
Support for RFC 2822 headers has been added to the
|
||||||
for README-type files and other standalone documents in the
|
reStructuredText parser for PEPs (unambiguous given a specific
|
||||||
Python distribution.
|
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.
|
||||||
|
|
||||||
|
|
||||||
Rationale
|
Rationale
|
||||||
|
|
||||||
The __doc__ attribute is called a documentation string, or
|
The lack of a standard syntax for docstrings has hampered the
|
||||||
docstring. It is often used to summarize the interface of the
|
development of standard tools for extracting and converting
|
||||||
module, class or function. The lack of a standard syntax for
|
docstrings into documentation in standard formats (e.g., HTML,
|
||||||
docstrings has hampered the development of standard tools for
|
DocBook, TeX). There have been a number of proposed markup
|
||||||
extracting docstrings and transforming them into documentation in
|
formats and variations, and many tools tied to these proposals,
|
||||||
standard formats (e.g., HTML, DocBook, TeX). There have been a
|
but without a standard docstring format they have failed to gain a
|
||||||
number of proposed markup formats and variations, and many tools
|
strong following and/or floundered half-finished.
|
||||||
tied to these proposals, but without a standard docstring format
|
|
||||||
they have failed to gain a strong following and/or floundered
|
|
||||||
half-finished.
|
|
||||||
|
|
||||||
The adoption of a standard will, at the very least, benefit
|
|
||||||
docstring processing tools by preventing further "reinventing the
|
|
||||||
wheel".
|
|
||||||
|
|
||||||
Throughout the existence of the Doc-SIG, consensus on a single
|
Throughout the existence of the Doc-SIG, consensus on a single
|
||||||
standard docstring format has never been reached. A lightweight,
|
standard docstring format has never been reached. A lightweight,
|
||||||
|
|
@ -118,12 +166,12 @@ Rationale
|
||||||
others):
|
others):
|
||||||
|
|
||||||
1. Docstrings written within Python code are available from within
|
1. Docstrings written within Python code are available from within
|
||||||
the interactive interpreter, and can be 'print'ed. Thus the
|
the interactive interpreter, and can be "print"ed. Thus the
|
||||||
use of plaintext for easy readability.
|
use of plaintext for easy readability.
|
||||||
|
|
||||||
2. Programmers want to add structure to their docstrings, without
|
2. Programmers want to add structure to their docstrings, without
|
||||||
sacrificing raw docstring readability. Unadorned plaintext
|
sacrificing raw docstring readability. Unadorned plaintext
|
||||||
cannot be transformed ('up-translated') into useful structured
|
cannot be transformed ("up-translated") into useful structured
|
||||||
formats.
|
formats.
|
||||||
|
|
||||||
3. Explicit markup (like XML or TeX) is widely considered
|
3. Explicit markup (like XML or TeX) is widely considered
|
||||||
|
|
@ -132,27 +180,32 @@ Rationale
|
||||||
4. Implicit markup is aesthetically compatible with the clean and
|
4. Implicit markup is aesthetically compatible with the clean and
|
||||||
minimalist Python syntax.
|
minimalist Python syntax.
|
||||||
|
|
||||||
Proposed alternatives have included:
|
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 *not* 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.
|
||||||
|
|
||||||
- XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_
|
- XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_
|
||||||
|
|
||||||
XML and SGML are explicit, well-formed meta-languages suitable
|
XML and SGML are explicit, well-formed meta-languages suitable
|
||||||
for all kinds of documentation. XML is a variant of SGML. They
|
for all kinds of documentation. XML is a variant of SGML. They
|
||||||
are best used behind the scenes, because they are verbose,
|
are best used behind the scenes, because to untrained eyes they
|
||||||
difficult to type, and too cluttered to read comfortably as
|
are verbose, difficult to type, and too cluttered to read
|
||||||
source. DocBook, HTML, and XHTML are all applications of SGML
|
comfortably as source. DocBook, HTML, and XHTML are all
|
||||||
and/or XML, and all share the same basic syntax and the same
|
applications of SGML and/or XML, and all share the same basic
|
||||||
shortcomings.
|
syntax and the same shortcomings.
|
||||||
|
|
||||||
- TeX [8]_
|
- TeX [8]_
|
||||||
|
|
||||||
TeX is similar to XML/SGML in that it's explicit, not very easy
|
TeX is similar to XML/SGML in that it's explicit, but not very
|
||||||
to write, and not easy for the uninitiated to read.
|
easy to write, and not easy for the uninitiated to read.
|
||||||
|
|
||||||
- Perl POD [9]_
|
- Perl POD [9]_
|
||||||
|
|
||||||
Most Perl modules are documented in a format called POD -- Plain
|
Most Perl modules are documented in a format called POD (Plain
|
||||||
Old Documentation. This is an easy-to-type, very low level
|
Old Documentation). This is an easy-to-type, very low level
|
||||||
format with strong integration with the Perl parser. Many tools
|
format with strong integration with the Perl parser. Many tools
|
||||||
exist to turn POD documentation into other formats: info, HTML
|
exist to turn POD documentation into other formats: info, HTML
|
||||||
and man pages, among others. However, the POD syntax takes
|
and man pages, among others. However, the POD syntax takes
|
||||||
|
|
@ -163,17 +216,16 @@ Rationale
|
||||||
Special comments before Java classes and functions serve to
|
Special comments before Java classes and functions serve to
|
||||||
document the code. A program to extract these, and turn them
|
document the code. A program to extract these, and turn them
|
||||||
into HTML documentation is called javadoc, and is part of the
|
into HTML documentation is called javadoc, and is part of the
|
||||||
standard Java distribution. However, the only output format
|
standard Java distribution. However, JavaDoc has a very
|
||||||
that is supported is HTML, and JavaDoc has a very intimate
|
intimate relationship with HTML, using HTML tags for most
|
||||||
relationship with HTML, using HTML tags for most markup. Thus
|
markup. Thus it shares the readability problems of HTML.
|
||||||
it shares the readability problems of HTML.
|
|
||||||
|
|
||||||
- Setext [11]_, StructuredText [12]_
|
- Setext [11]_, StructuredText [12]_
|
||||||
|
|
||||||
Early on, variants of Setext (Structure Enhanced Text),
|
Early on, variants of Setext (Structure Enhanced Text),
|
||||||
including Zope Corp's StructuredText, were proposed for Python
|
including Zope Corp's StructuredText, were proposed for Python
|
||||||
docstring formatting. Hereafter these variants will
|
docstring formatting. Hereafter these variants will
|
||||||
collectively be call 'STexts'. STexts have the advantage of
|
collectively be called "STexts". STexts have the advantage of
|
||||||
being easy to read without special knowledge, and relatively
|
being easy to read without special knowledge, and relatively
|
||||||
easy to write.
|
easy to write.
|
||||||
|
|
||||||
|
|
@ -188,7 +240,8 @@ Rationale
|
||||||
requirements.
|
requirements.
|
||||||
|
|
||||||
- STexts have been sometimes surprising. Bits of text are
|
- STexts have been sometimes surprising. Bits of text are
|
||||||
marked up unexpectedly, leading to user frustration.
|
unexpectedly interpreted as being marked up, leading to user
|
||||||
|
frustration.
|
||||||
|
|
||||||
- SText implementations have been buggy.
|
- SText implementations have been buggy.
|
||||||
|
|
||||||
|
|
@ -198,6 +251,7 @@ Rationale
|
||||||
|
|
||||||
- There has been no mechanism to get around the SText markup
|
- There has been no mechanism to get around the SText markup
|
||||||
rules when a markup character is used in a non-markup context.
|
rules when a markup character is used in a non-markup context.
|
||||||
|
In other words, no way to escape markup.
|
||||||
|
|
||||||
Proponents of implicit STexts have vigorously opposed proposals
|
Proponents of implicit STexts have vigorously opposed proposals
|
||||||
for explicit markup (XML, HTML, TeX, POD, etc.), and the debates
|
for explicit markup (XML, HTML, TeX, POD, etc.), and the debates
|
||||||
|
|
@ -207,29 +261,31 @@ Rationale
|
||||||
the SText idea, addressing all of the problems listed above.
|
the SText idea, addressing all of the problems listed above.
|
||||||
|
|
||||||
|
|
||||||
Features
|
Specification
|
||||||
|
|
||||||
Rather than repeating or summarizing the extensive
|
The specification and user documentaton for reStructuredText is
|
||||||
reStructuredText spec, please read the originals available from
|
quite extensive. Rather than repeating or summarizing it all
|
||||||
http://structuredtext.sourceforge.net/spec/ (.txt & .html files).
|
here, links to the originals are provided.
|
||||||
Reading the documents in following order is recommended:
|
|
||||||
|
|
||||||
- An Introduction to reStructuredText [13]_
|
Please first take a look at "A ReStructuredText Primer" [13]_, a
|
||||||
|
short and gentle introduction. The "Quick reStructuredText" user
|
||||||
|
reference [14]_ quickly summarizes all of the markup constructs.
|
||||||
|
For complete and extensive details, please refer to the following
|
||||||
|
documents:
|
||||||
|
|
||||||
- Problems With StructuredText [14]_ (optional, if you've used
|
- An Introduction to reStructuredText [15]_
|
||||||
StructuredText; it explains many markup decisions made)
|
|
||||||
|
|
||||||
- reStructuredText Markup Specification [15]_
|
- reStructuredText Markup Specification [16]_
|
||||||
|
|
||||||
- A Record of reStructuredText Syntax Alternatives [16]_ (explains
|
|
||||||
markup decisions made independently of StructuredText)
|
|
||||||
|
|
||||||
- reStructuredText Directives [17]_
|
- reStructuredText Directives [17]_
|
||||||
|
|
||||||
There is also a "Quick reStructuredText" user reference [18]_.
|
In addition, "Problems With StructuredText" [18]_ explains many
|
||||||
|
markup decisions made with regards to StructuredText, and "A
|
||||||
|
Record of reStructuredText Syntax Alternatives" [19]_ records
|
||||||
|
markup decisions made independently.
|
||||||
|
|
||||||
A summary of features addressing often-raised docstring markup
|
|
||||||
concerns follows:
|
Docstring-Significant Features
|
||||||
|
|
||||||
- A markup escaping mechanism.
|
- A markup escaping mechanism.
|
||||||
|
|
||||||
|
|
@ -288,6 +344,8 @@ Features
|
||||||
class Keeper(Storer):
|
class Keeper(Storer):
|
||||||
|
|
||||||
"""
|
"""
|
||||||
|
Keep data fresher longer.
|
||||||
|
|
||||||
Extend `Storer`. Class attribute `instances` keeps track
|
Extend `Storer`. Class attribute `instances` keeps track
|
||||||
of the number of `Keeper` objects instantiated.
|
of the number of `Keeper` objects instantiated.
|
||||||
"""
|
"""
|
||||||
|
|
@ -340,9 +398,10 @@ Features
|
||||||
These are mostly used for extension syntax, such as
|
These are mostly used for extension syntax, such as
|
||||||
"bibliographic field lists" (representing document metadata such
|
"bibliographic field lists" (representing document metadata such
|
||||||
as author, date, and version) and extension attributes for
|
as author, date, and version) and extension attributes for
|
||||||
directives (see below). They may be used to implement docstring
|
directives (see below). They may be used to implement
|
||||||
semantics, such as identifying parameters, exceptions raised,
|
methodologies (docstring semantics), such as identifying
|
||||||
etc.; such usage is beyond the scope of this PEP.
|
parameters, exceptions raised, etc.; such usage is beyond the
|
||||||
|
scope of this PEP.
|
||||||
|
|
||||||
A modified RFC 2822 syntax is used, with a colon *before* as
|
A modified RFC 2822 syntax is used, with a colon *before* as
|
||||||
well as *after* the field name. Field bodies are more versatile
|
well as *after* the field name. Field bodies are more versatile
|
||||||
|
|
@ -358,11 +417,7 @@ Features
|
||||||
|
|
||||||
Standard RFC 2822 header syntax cannot be used for this
|
Standard RFC 2822 header syntax cannot be used for this
|
||||||
construct because it is ambiguous. A word followed by a colon
|
construct because it is ambiguous. A word followed by a colon
|
||||||
at the beginning of a line is common in written text. However,
|
at the beginning of a line is common in written text.
|
||||||
with the addition of a well-defined context, such as when a
|
|
||||||
field list invariably occurs at the beginning of a document
|
|
||||||
(e.g., PEPs and email messages), standard RFC 2822 header syntax
|
|
||||||
can be used.
|
|
||||||
|
|
||||||
- Markup extensibility: directives and substitutions.
|
- Markup extensibility: directives and substitutions.
|
||||||
|
|
||||||
|
|
@ -381,7 +436,7 @@ Features
|
||||||
|
|
||||||
The |biohazard| symbol must be used on containers used to
|
The |biohazard| symbol must be used on containers used to
|
||||||
dispose of medical waste.
|
dispose of medical waste.
|
||||||
|
|
||||||
.. |biohazard| image:: biohazard.png
|
.. |biohazard| image:: biohazard.png
|
||||||
|
|
||||||
- Section structure markup.
|
- Section structure markup.
|
||||||
|
|
@ -405,25 +460,26 @@ Features
|
||||||
|
|
||||||
Questions & Answers
|
Questions & Answers
|
||||||
|
|
||||||
Q: Is reStructuredText rich enough?
|
1. Is reStructuredText rich enough?
|
||||||
|
|
||||||
A: Yes, it is for most people. If it lacks some construct that is
|
Yes, it is for most people. If it lacks some construct that is
|
||||||
require for a specific application, it can be added via the
|
required for a specific application, it can be added via the
|
||||||
directive mechanism. If a common construct has been
|
directive mechanism. If a useful and common construct has been
|
||||||
overlooked and a suitably readable syntax can be found, it can
|
overlooked and a suitably readable syntax can be found, it can
|
||||||
be added to the specification and parser.
|
be added to the specification and parser.
|
||||||
|
|
||||||
Q: Is reStructuredText *too* rich?
|
2. Is reStructuredText *too* rich?
|
||||||
|
|
||||||
A: No.
|
For specific applications or individuals, perhaps. In general,
|
||||||
|
no.
|
||||||
|
|
||||||
Since the very beginning, whenever a markup syntax has been
|
Since the very beginning, whenever a docstring markup syntax
|
||||||
proposed on the Doc-SIG, someone has complained about the lack
|
has been proposed on the Doc-SIG, someone has complained about
|
||||||
of support for some construct or other. The reply was often
|
the lack of support for some construct or other. The reply was
|
||||||
something like, "These are docstrings we're talking about, and
|
often something like, "These are docstrings we're talking
|
||||||
docstrings shouldn't have complex markup." The problem is that
|
about, and docstrings shouldn't have complex markup." The
|
||||||
a construct that seems superfluous to one person may be
|
problem is that a construct that seems superfluous to one
|
||||||
absolutely essential to another.
|
person may be absolutely essential to another.
|
||||||
|
|
||||||
reStructuredText takes the opposite approach: it provides a
|
reStructuredText takes the opposite approach: it provides a
|
||||||
rich set of implicit markup constructs (plus a generic
|
rich set of implicit markup constructs (plus a generic
|
||||||
|
|
@ -433,10 +489,10 @@ Questions & Answers
|
||||||
removed from the parser (via application-specific overrides) or
|
removed from the parser (via application-specific overrides) or
|
||||||
simply omitted by convention.
|
simply omitted by convention.
|
||||||
|
|
||||||
Q: Why not use indentation for section structure, like
|
3. Why not use indentation for section structure, like
|
||||||
StructuredText does? Isn't it more "Pythonic"?
|
StructuredText does? Isn't it more "Pythonic"?
|
||||||
|
|
||||||
A: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG
|
Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG
|
||||||
post:
|
post:
|
||||||
|
|
||||||
I still think that using indentation to indicate sectioning
|
I still think that using indentation to indicate sectioning
|
||||||
|
|
@ -455,20 +511,20 @@ Questions & Answers
|
||||||
over 30 centuries. Let's not innovate needlessly.
|
over 30 centuries. Let's not innovate needlessly.
|
||||||
|
|
||||||
See "Section Structure via Indentation" in "Problems With
|
See "Section Structure via Indentation" in "Problems With
|
||||||
StructuredText" [14 ]_ for further elaboration.
|
StructuredText" [18 ]_ for further elaboration.
|
||||||
|
|
||||||
Q: Why use reStructuredText for PEPs? What's wrong with the
|
4. Why use reStructuredText for PEPs? What's wrong with the
|
||||||
existing standard?
|
existing standard?
|
||||||
|
|
||||||
A: The existing standard for PEPs is very limited in terms of
|
The existing standard for PEPs is very limited in terms of
|
||||||
general expressibility, and referencing is especially lacking
|
general expressibility, and referencing is especially lacking
|
||||||
for such a reference-rich document type. PEPs are currently
|
for such a reference-rich document type. PEPs are currently
|
||||||
converted into HTML, but the results (mostly monospaced text)
|
converted into HTML, but the results (mostly monospaced text)
|
||||||
are less than attractive, and most of the value-added potential
|
are less than attractive, and most of the value-added potential
|
||||||
of HTML is untapped.
|
of HTML (especially inline hyperlinks) is untapped.
|
||||||
|
|
||||||
Making reStructuredText the standard markup for PEPs will
|
Making reStructuredText a standard markup for PEPs will enable
|
||||||
enable much richer expression, including support for section
|
much richer expression, including support for section
|
||||||
structure, inline markup, graphics, and tables. In several
|
structure, inline markup, graphics, and tables. In several
|
||||||
PEPs there are ASCII graphics diagrams, which are all that
|
PEPs there are ASCII graphics diagrams, which are all that
|
||||||
plaintext documents can support. Since PEPs are made available
|
plaintext documents can support. Since PEPs are made available
|
||||||
|
|
@ -497,13 +553,13 @@ Questions & Answers
|
||||||
|
|
||||||
Abstract
|
Abstract
|
||||||
|
|
||||||
This PEP proposes a adding frungible doodads [1] to the
|
This PEP proposes adding frungible doodads [1] to the
|
||||||
core. It extends PEP 9876 [2] via the BCA [3]
|
core. It extends PEP 9876 [2] via the BCA [3]
|
||||||
mechanism.
|
mechanism.
|
||||||
|
|
||||||
References and Footnotes
|
References and Footnotes
|
||||||
|
|
||||||
[1] http://www.doodads.org/frungible.html
|
[1] http://www.example.org/
|
||||||
|
|
||||||
[2] PEP 9876, Let's Hope We Never Get Here
|
[2] PEP 9876, Let's Hope We Never Get Here
|
||||||
http://www.python.org/peps/pep-9876.html
|
http://www.python.org/peps/pep-9876.html
|
||||||
|
|
@ -518,16 +574,17 @@ Questions & Answers
|
||||||
Abstract
|
Abstract
|
||||||
========
|
========
|
||||||
|
|
||||||
This PEP proposes a adding `frungible doodads`_ to the
|
This PEP proposes adding `frungible doodads`_ to the core.
|
||||||
core. It extends PEP 9876 [#pep9876] via the BCA [#]
|
It extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.
|
||||||
mechanism.
|
|
||||||
|
|
||||||
.. _frungible doodads:
|
...
|
||||||
http://www.doodads.org/frungible.html
|
|
||||||
|
References & Footnotes
|
||||||
|
======================
|
||||||
|
|
||||||
.. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here
|
.. _frungible doodads: http://www.example.org/
|
||||||
|
|
||||||
__ http://www.python.org/peps/pep-9876.html
|
.. [#pep9876] PEP 9876, Let's Hope We Never Get Here
|
||||||
|
|
||||||
.. [#] "Bogus Complexity Addition"
|
.. [#] "Bogus Complexity Addition"
|
||||||
|
|
||||||
|
|
@ -543,7 +600,7 @@ Questions & Answers
|
||||||
URL references can be named ("frungible doodads"), and can be
|
URL references can be named ("frungible doodads"), and can be
|
||||||
referenced from multiple places in the document without
|
referenced from multiple places in the document without
|
||||||
additional definitions. When converted to HTML, references
|
additional definitions. When converted to HTML, references
|
||||||
will be replaced with inline hyperlinks (HTML <A> tags). The
|
will be replaced with inline hyperlinks (HTML <a> tags). The
|
||||||
two footnotes are automatically numbered, so they will always
|
two footnotes are automatically numbered, so they will always
|
||||||
stay in sync. The first footnote also contains an internal
|
stay in sync. The first footnote also contains an internal
|
||||||
reference name, "pep9876", so it's easier to see the connection
|
reference name, "pep9876", so it's easier to see the connection
|
||||||
|
|
@ -556,54 +613,123 @@ Questions & Answers
|
||||||
|
|
||||||
It extends PEP 9876 [PEP9876]_ ...
|
It extends PEP 9876 [PEP9876]_ ...
|
||||||
|
|
||||||
.. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here
|
.. [PEP9876] PEP 9876, Let's Hope We Never Get Here
|
||||||
|
|
||||||
Footnotes are numbered, whereas citations use text for their
|
Footnotes are numbered, whereas citations use text for their
|
||||||
references.
|
references.
|
||||||
|
|
||||||
Q: Wouldn't it be better to keep the docstring and PEP proposals
|
5. Wouldn't it be better to keep the docstring and PEP proposals
|
||||||
separate?
|
separate?
|
||||||
|
|
||||||
A: The PEP markup proposal is an option to this PEP. It may be
|
The PEP markup proposal may be removed if it is deemed that
|
||||||
removed if it is deemed that there is no need for PEP markup.
|
there is no need for PEP markup, or it could be made into a
|
||||||
The PEP markup proposal could be made into a separate PEP if
|
separate PEP. If accepted, PEP 1, PEP Purpose and Guidelines
|
||||||
necessary. If accepted, PEP 1, PEP Purpose and Guidelines [19]_,
|
[20]_, and PEP 9, Sample PEP Template [21]_ will be updated.
|
||||||
and PEP 9, Sample PEP Template [20]_ will be updated.
|
|
||||||
|
|
||||||
It seems natural to adopt a single consistent markup standard
|
It seems natural to adopt a single consistent markup standard
|
||||||
for all uses of plaintext in Python.
|
for all uses of structured plaintext in Python, and to propose
|
||||||
|
it all in one place.
|
||||||
|
|
||||||
Q: The existing pep2html.py script converts the existing PEP
|
6. The existing pep2html.py script converts the existing PEP
|
||||||
format to HTML. How will the new-format PEPs be converted to
|
format to HTML. How will the new-format PEPs be converted to
|
||||||
HTML?
|
HTML?
|
||||||
|
|
||||||
A: One of the deliverables of the Docutils project [21]_ will be a
|
One of the deliverables of the Docutils project [22]_ will be a
|
||||||
new version of pep2html.py with integrated reStructuredText
|
new version of pep2html.py with integrated reStructuredText
|
||||||
parsing. The Docutils project will support PEPs with a "PEP
|
parsing. The Docutils project will support PEPs with a "PEP
|
||||||
Reader" component, including all functionality currently in
|
Reader" component, including all functionality currently in
|
||||||
pep2html.py (auto-recognition of PEP & RFC references).
|
pep2html.py (auto-recognition of PEP & RFC references).
|
||||||
|
|
||||||
Q: Who's going to convert the existing PEPs to reStructuredText?
|
7. Who's going to convert the existing PEPs to reStructuredText?
|
||||||
|
|
||||||
A: A call for volunteers will be put out to the Doc-SIG and
|
PEP authors or volunteers may convert existing PEPs if they
|
||||||
greater Python communities. If insufficient volunteers are
|
like, but there is no requirement to do so. The
|
||||||
forthcoming, I (David Goodger) will convert the documents
|
reStructuredText-based PEPs will coexist with the old PEP
|
||||||
myself, perhaps with some level of automation. A transitional
|
standard. The pep2html.py mentioned in answer 6 will process
|
||||||
system whereby both old and new standards can coexist will be
|
both old and new standards.
|
||||||
easy to implement (and I pledge to implement it if necessary).
|
|
||||||
|
|
||||||
Q: Why use reStructuredText for README and other ancillary files?
|
8. Why use reStructuredText for README and other ancillary files?
|
||||||
|
|
||||||
A: The same reasoning used for PEPs above applies to README and
|
The reasoning given for PEPs in answer 4 above also applies to
|
||||||
other ancillary files. By adopting a standard markup, these
|
README and other ancillary files. By adopting a standard
|
||||||
files can be converted to attractive cross-referenced HTML and
|
markup, these files can be converted to attractive
|
||||||
put up on python.org. Developers of Python projects can also
|
cross-referenced HTML and put up on python.org. Developers of
|
||||||
take advantage of this facility for their own documentation.
|
Python projects can also take advantage of this facility for
|
||||||
|
their own documentation.
|
||||||
|
|
||||||
|
9. 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?
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
In a strict sense, the reStructuredText parser is very
|
||||||
|
unforgiving (as it should be; "In the face of ambiguity, refuse
|
||||||
|
the temptation to guess" [23]_ applies to parsing markup as
|
||||||
|
well as computer languages). Here's design goal 3 from "An
|
||||||
|
Introduction to reStructuredText" [15 ]_:
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
10. Will the docstrings in the Python standard library modules be
|
||||||
|
converted to reStructuredText?
|
||||||
|
|
||||||
|
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 *do*
|
||||||
|
contain ad-hoc implicit markup).
|
||||||
|
|
||||||
|
11. I want to write all my strings in Unicode. Will anything
|
||||||
|
break?
|
||||||
|
|
||||||
|
The parser fully supports Unicode. Docutils supports
|
||||||
|
arbitrary input encodings.
|
||||||
|
|
||||||
|
12. Why does the community need a new structured text design?
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
13. What is wrong with existing documentation methodologies?
|
||||||
|
|
||||||
|
What existing methodologies? For Python docstrings, there is
|
||||||
|
**no** 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.
|
||||||
|
|
||||||
|
|
||||||
References and Footnotes
|
References & Footnotes
|
||||||
|
|
||||||
[1] http://structuredtext.sourceforge.net/
|
[1] http://docutils.sourceforge.net/spec/rst.html
|
||||||
|
|
||||||
[2] http://www.python.org/sigs/doc-sig/
|
[2] http://www.python.org/sigs/doc-sig/
|
||||||
|
|
||||||
|
|
@ -627,33 +753,40 @@ References and Footnotes
|
||||||
|
|
||||||
[12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
|
[12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
|
||||||
|
|
||||||
[13] An Introduction to reStructuredText
|
[13] A ReStructuredText Primer
|
||||||
http://structuredtext.sourceforge.net/spec/introduction.txt
|
http://docutils.sourceforge.net/docs/rst/quickstart.html
|
||||||
|
|
||||||
[14] Problems with StructuredText
|
[14] Quick reStructuredText
|
||||||
http://structuredtext.sourceforge.net/spec/problems.txt
|
http://docutils.sourceforge.net/docs/rst/quickref.html
|
||||||
|
|
||||||
[15] reStructuredText Markup Specification
|
[15] An Introduction to reStructuredText
|
||||||
http://structuredtext.sourceforge.net/spec/reStructuredText.txt
|
http://docutils.sourceforge.net/spec/rst/introduction.html
|
||||||
|
|
||||||
[16] A Record of reStructuredText Syntax Alternatives
|
[16] reStructuredText Markup Specification
|
||||||
http://structuredtext.sourceforge.net/spec/alternatives.txt
|
http://docutils.sourceforge.net/spec/rst/reStructuredText.html
|
||||||
|
|
||||||
[17] reStructuredText Directives
|
[17] reStructuredText Directives
|
||||||
http://structuredtext.sourceforge.net/spec/directives.txt
|
http://docutils.sourceforge.net/spec/rst/directives.html
|
||||||
|
|
||||||
[18] Quick reStructuredText
|
[18] Problems with StructuredText
|
||||||
http://structuredtext.sourceforge.net/docs/quickref.html
|
http://docutils.sourceforge.net/spec/rst/problems.html
|
||||||
|
|
||||||
[19] PEP 1, PEP Guidelines, Warsaw, Hylton
|
[19] A Record of reStructuredText Syntax Alternatives
|
||||||
|
http://docutils.sourceforge.net/spec/rst/alternatives.html
|
||||||
|
|
||||||
|
[20] PEP 1, PEP Guidelines, Warsaw, Hylton
|
||||||
http://www.python.org/peps/pep-0001.html
|
http://www.python.org/peps/pep-0001.html
|
||||||
|
|
||||||
[20] PEP 9, Sample PEP Template, Warsaw
|
[21] PEP 9, Sample PEP Template, Warsaw
|
||||||
http://www.python.org/peps/pep-0009.html
|
http://www.python.org/peps/pep-0009.html
|
||||||
|
|
||||||
[21] http://docutils.sourceforge.net/
|
[22] http://docutils.sourceforge.net/
|
||||||
|
|
||||||
[22] PEP 216, Docstring Format, Zadka
|
[23] From "The Zen of Python (by Tim Peters)"
|
||||||
|
(http://www.python.org/doc/Humor.html#zen or just
|
||||||
|
"``import this``" in Python)
|
||||||
|
|
||||||
|
[24] PEP 216, Docstring Format, Zadka
|
||||||
http://www.python.org/peps/pep-0216.html
|
http://www.python.org/peps/pep-0216.html
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -664,10 +797,11 @@ Copyright
|
||||||
|
|
||||||
Acknowledgements
|
Acknowledgements
|
||||||
|
|
||||||
Some text is borrowed from PEP 216, Docstring Format, by Moshe
|
Some text is borrowed from PEP 216, Docstring Format [24]_, by
|
||||||
Zadka [22]_.
|
Moshe Zadka.
|
||||||
|
|
||||||
Special thanks to all members past & present of the Python Doc-SIG.
|
Special thanks to all members past & present of the Python
|
||||||
|
Doc-SIG.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue