iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2002-08-01 22:32:33 +00:00
parent 4f0ce75e88
commit 0c228b0b73
5 changed files with 1278 additions and 587 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
pep-0000.txt
View File

@ -74,7 +74,7 @@ Index by Category
S 254 Making Classes Look More Like Types van Rossum
S 256 Docstring Processing System Framework Goodger
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 263 Defining Python Source Code Encodings Lemburg
S 265 Sorting Dictionaries by Value Griffin
@ -95,7 +95,7 @@ Index by Category
I 283 Python 2.3 Release Schedule van Rossum
S 284 Integer for-loops Eppstein, Ewing
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
S 292 Simpler String Substitutions Warsaw
S 293 Codec Error Handling Callbacks Dörwald
@ -246,7 +246,7 @@ Numerical Index
SF 255 Simple Generators Schemenauer, et al
S 256 Docstring Processing System Framework Goodger
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
SF 260 Simplify xrange() van Rossum
S 261 Support for "wide" Unicode characters Prescod
@ -275,7 +275,7 @@ Numerical Index
S 284 Integer for-loops Eppstein, Ewing
SF 285 Adding a bool type van Rossum
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
SR 289 Generator Comprehensions Hettinger
I 290 Code Migration and Modernization Hettinger

368
pep-0256.txt
View File

@ -2,167 +2,154 @@ PEP: 256
Title: Docstring Processing System Framework
Version: $Revision$
Last-Modified: $Date$
Author: dgoodger@bigfoot.com (David Goodger)
Author: goodger@users.sourceforge.net (David Goodger)
Discussions-To: doc-sig@python.org
Status: Draft
Type: Standards Track
Requires: PEP 257 Docstring Conventions
PEP 258 DPS Generic Implementation Details
Created: 01-Jun-2001
Post-History:
Post-History: 13-Jun-2001
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
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
tools for extracting and processing Python docstrings. The lack
of a standard toolset is a significant gap in Python's
infrastructure; this PEP aims to fill the gap.
There are standard inline documentation systems for some other
languages. For example, Perl has POD (plain old documentation)
and Java has Javadoc, but neither of these mesh with the Pythonic
way. POD 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 and Web (Tangle & Weave), useful for multiple languages.
The issues surrounding docstring processing have been contentious
and difficult to resolve. This PEP proposes a generic Docstring
Processing System (DPS) framework, which 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 (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):
- 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
standard library; see below)
- Ka-Ping Yee's htmldoc & pydoc [10]_ (pydoc.py is now part of the
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
of success. A problem with many of the above systems was
over-ambition. They provided a self-contained set of components: a
docstring extraction system, an input parser, an internal
processing system and one or more output formatters. Inevitably,
one or more components had serious shortcomings, preventing the
system from being adopted as a standard tool.
Throughout the existence of the Python Documentation Special
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.
over-ambition combined with inflexibility. They provided a
self-contained set of components: a docstring extraction system, a
markup parser, an internal processing system and one or more
output format writers with a fixed style. Inevitably, one or more
aspects of each system had serious shortcomings, and they were not
easily extended or modified, preventing them from being adopted as
standard tools.
It has become clear (to this author, at least) that the "all or
nothing" approach cannot succeed, since no all-encompassing
proposal could possibly be agreed upon by all interested parties.
A modular component approach, where components may be multiply
implemented, is the only chance at success. By separating out the
issues, we can form consensus more easily (smaller fights ;-), and
accept divergence more readily.
nothing" approach cannot succeed, since no monolithic
self-contained system could possibly be agreed upon by all
interested parties. A modular component approach designed for
extension, where components may be multiply implemented, may be
the only chance for success. Standard inter-component APIs will
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
developed independently. A 'best of breed' system should be
chosen and/or developed and eventually included in Python's
standard library.
chosen, either merged from existing systems, and/or developed
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
displays docstrings from within the Python interactive
interpreter, from the shell command line, and from a GUI window
into a web browser (HTML). In the case of GUI/HTML, except for
some heuristic 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 pretty.
PyDoc became part of the Python standard library as of release
2.1. It extracts and displays docstrings from within the Python
interactive interpreter, from the shell command line, and from a
GUI window into a web browser (HTML). Although a very useful
tool, PyDoc has several deficiencies, including:
- In the case of the GUI/HTML, except for some heuristic
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
by pydoc when serving HTML pages. However, the proposed docstring
processing system's functionality is much more than pydoc needs
(in its current form). Either an independent tool will be
developed (which pydoc may or may not use), or pydoc could be
expanded to encompass this functionality and *become* the
docstring processing system (or one such system). That decision
is beyond the scope of this PEP.
by PyDoc when serving HTML pages. The proposed docstring
processing system's functionality is much more than PyDoc needs in
its current form. Either an independent tool will be developed
(which PyDoc may or may not use), or PyDoc could be expanded to
encompass this functionality and *become* the docstring processing
system (or one such system). That decision is beyond the scope of
this PEP.
Similarly for other existing docstring processing systems, their
authors may or may not choose compatibility with this framework.
@ -182,115 +169,106 @@ Specification
- 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.
Documents issues such as:
2. Docstring processing system design specification. Documents
issues such as:
- High-level spec: what a DPS does.
- Command-line interface for executable script.
- System Python API
- System Python API.
- Docstring extraction rules.
- Input parser API.
- Readers, which encapsulate the input context .
- Intermediate internal data structure: output from input parser,
input to output formatter.
- Parsers.
- 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
implementation. PEP 258, DPS Generic Implementation
Details[13], documents these issues.
implementation. PEP 258, Docutils Design Specification [13 ]_,
documents these issues.
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.
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
PEPs, although they may be merged into this PEP once consensus is
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.
8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
implementations.
The following diagram shows an overview of the framework.
Interfaces are indicated by double-borders. The ASCII diagram is
very wide; please turn off line wrapping to view it:
+========================+
| 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 |
+-------------+ +-----------+-------------------+-----------+ +--------+
Components 1, 2/3, and 4/5 are the subject of individual companion
PEPs. If there is another implementation of the framework or
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.
Project Web Site
A SourceForge project has been set up for this work at
http://docstring.sf.net.
http://docutils.sourceforge.net/.
References and Footnotes
[1] PEP 236, Docstring Format, Zadka
http://www.python.org/peps/pep-0216.html
[1] http://www.literateprogramming.com/
[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
[13] PEP 258, DPS Generic Implementation Details, Goodger
http://www.python.org/peps/pep-0258.html
[15] PEP 287, reStructuredText Docstring Format, Goodger
http://www.python.org/peps/pep-0287.html
[16] http://www.python.org/sigs/doc-sig/
Copyright
@ -300,16 +278,14 @@ Copyright
Acknowledgements
This document borrows text from PEP 216, Docstring Format by Moshe
Zadka[1]. It is intended as a reorganization of PEP 216 and its
approach.
This document also borrows ideas from the archives of the Python
Doc-SIG. Thanks to all members past & present.
This document borrows ideas from the archives of the Python
Doc-SIG [16]_. Thanks to all members past & present.
Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
sentence-end-double-space: t
End:

85
pep-0257.txt
View File

@ -2,10 +2,10 @@ PEP: 257
Title: Docstring Conventions
Version: $Revision$
Last-Modified: $Date$
Author: dgoodger@bigfoot.com (David Goodger),
guido@digicool.com (Guido van Rossum)
Author: goodger@users.sourceforge.net (David Goodger),
guido@python.org (Guido van Rossum)
Discussions-To: doc-sig@python.org
Status: Draft
Status: Active
Type: Informational
Created: 29-May-2001
Post-History: 13-Jun-2001
@ -32,9 +32,9 @@ Rationale
--Tim Peters on comp.lang.python, 2001-06-16
If you violate the conventions, the worst you'll get is some dirty
looks. But some software (such as the Docstring Processing System
[1]) will be aware of the conventions, so following them will get
you the best results.
looks. But some software (such as the Docutils docstring
processing system [1] [2]) will be aware of the conventions, so
following them will get you the best results.
Specification
@ -43,7 +43,7 @@ Specification
--------------------
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.
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
of the __init__.py file in the package directory.
String literals occuring elsewhere in Python code may also act as
documentation. They are not recognized by the Python bytecode
String literals occurring elsewhere in Python code may also act as
documentation. They are not recognized by the Python bytecode
compiler and are not accessible as runtime object attributes
(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
are called "attribute docstrings".
2. String literals occuring immediately after another docstring
2. String literals occurring immediately after another docstring
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.
XXX Mention docstrings of 2.2 properties.
For consistency, always use """triple double quotes""" around
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
docstrings.
@ -87,7 +90,7 @@ Specification
if _kos_root: return _kos_root
...
Notes:
Notes:
- Triple quotes are used even though the string fits on one line.
This makes it easy to later expand it.
@ -98,18 +101,27 @@ Specification
- There's no blank line either before or after the docstring.
- The docstring is a phrase ending in a period. It prescribes the
function's effect as a command ("Do this", "Return that"), not
as a description: e.g. don't write "Returns the pathname ..."
function or method's effect as a command ("Do this", "Return
that"), not as a description: e.g. don't write "Returns the
pathname ..."
- 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::
def function(a, b):
"""function(a, b) -> list"""
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
----------------------
@ -118,7 +130,9 @@ Specification
one-line docstring, followed by a blank line, followed by a more
elaborate description. The summary line may be used by automatic
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
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
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
header and the docstring. Docstrings documenting functions
generally don't have this requirement, unless the function's body
is written as a number of blank-line separated sections -- in this
case, treat the docstring as another section, and precede it with
a blank line.
header and the docstring. Docstrings documenting functions or
methods generally don't have this requirement, unless the function
or method's body is written as a number of blank-line separated
sections -- in this case, treat the docstring as another section,
and precede it with a blank line.
The docstring of a script (a stand-alone program) should be usable
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
by the module, with a one-line summary of each. (These summaries
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
subpackages exported by the package.
@ -183,16 +197,16 @@ Specification
functions or methods in upper case in running text. Python is
case sensitive and the argument names can be used for keyword
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::
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
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
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
[3] Guido van Rossum, Python's creator and Benevolent Dictator For
Life.
[4] PEP 8, Style Guide for Python Code, van Rossum, Warsaw
http://www.python.org/peps/pep-0008.html
[4] http://www.python.org/doc/essays/styleguide.html
[5] http://www.python.org/sigs/doc-sig/
@ -228,7 +241,7 @@ Copyright
Acknowledgements
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
Doc-SIG [5]. Thanks to all members past and present.
@ -238,4 +251,6 @@ Acknowledgements
Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
sentence-end-double-space: t
End:

922
pep-0258.txt
View File

File diff suppressed because it is too large Load Diff

482
pep-0287.txt
View File

@ -1,5 +1,5 @@
PEP: 287
Title: reStructuredText Standard Docstring Format
Title: reStructuredText Docstring Format
Version: $Revision$
Last-Modified: $Date$
Author: goodger@users.sourceforge.net (David Goodger)
@ -7,33 +7,86 @@ Discussions-To: doc-sig@python.org
Status: Draft
Type: Informational
Created: 25-Mar-2002
Post-History:
Post-History: 02-Apr-2002
Replaces: 216
Abstract
This PEP proposes that the reStructuredText [1]_ markup be adopted
as the standard markup format for plaintext documentation in
Python docstrings, and (optionally) for PEPs and ancillary
documents as well. reStructuredText is a rich and extensible yet
easy-to-read, what-you-see-is-what-you-get plaintext markup
syntax.
When plaintext hasn't been expressive enough for inline
documentation, Python programmers have sought out a format for
docstrings. This PEP proposes that the reStructuredText markup
[1]_ be adopted as a standard markup format for structured
plaintext documentation in Python docstrings, and for PEPs and
ancillary documents as well. reStructuredText is a rich and
extensible yet easy-to-read, what-you-see-is-what-you-get
plaintext markup syntax.
Only the low-level syntax of docstrings is addressed here. This
PEP is not concerned with docstring semantics or processing at
all.
PEP is not concerned with docstring semantics or processing at 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
These are the generally accepted goals for a docstring format, as
discussed in the Python Documentation Special Interest Group
(Doc-SIG) [2]_:
discussed in the Doc-SIG:
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
from parsing the module.
@ -44,21 +97,24 @@ Goals
5. It must be possible to write a module's entire documentation in
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
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:
1. To establish a standard docstring format by attaining
"accepted" status (Python community consensus; BDFL
pronouncement). Once reStructuredText is a Python standard,
all effort can be focused on tools instead of arguing for a
standard. Python needs a standard set of documentation tools.
1. To establish reStructuredText as a standard structured
plaintext format for docstrings (inline documentation of Python
modules and packages), PEPs, README-type files and other
standalone documents. "Accepted" status will be sought through
Python community consensus and eventual BDFL pronouncement.
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
markups are out there, the development community remains
@ -69,48 +125,40 @@ Goals
projects. It is hoped that interested developers will join
forces and work on a joint/merged/common implementation.
5. (Optional.) To adopt reStructuredText as the standard markup
for PEPs. One or both of the following strategies may be
applied:
Once reStructuredText is a Python standard, effort can be focused
on tools instead of arguing for a standard. Python needs a
standard set of documentation tools.
a) Keep the existing PEP section structure constructs (one-line
section headers, indented body text). Subsections can
either be forbidden or supported with underlined headers in
the indented body text.
With regard to PEPs, one or both of the following strategies may
be applied:
b) Replace the PEP section structure constructs with the
reStructuredText syntax. Section headers will require
underlines, subsections will be supported out of the box,
and body text need not be indented (except for block
quotes).
a) Keep the existing PEP section structure constructs (one-line
section headers, indented body text). Subsections can either
be forbidden, or supported with reStructuredText-style
underlined headers in the indented body text.
Support for RFC 2822 headers will be added to the
reStructuredText parser (unambiguous given a specific context:
the first contiguous block of a PEP document). It may be
desired to concretely specify what over/underline styles are
allowed for PEP section headers, for uniformity.
b) Replace the PEP section structure constructs with the
reStructuredText syntax. Section headers will require
underlines, subsections will be supported out of the box,
and body text need not be indented (except for block
quotes).
6. (Optional.) To adopt reStructuredText as the standard markup
for README-type files and other standalone documents in the
Python distribution.
Support for RFC 2822 headers has been added to the
reStructuredText parser for PEPs (unambiguous given a specific
context: the first contiguous block of the document). It may be
desired to concretely specify what over/underline styles are
allowed for PEP section headers, for uniformity.
Rationale
The __doc__ attribute is called a documentation string, or
docstring. It is often used to summarize the interface of the
module, class or function. The lack of a standard syntax for
docstrings has hampered the development of standard tools for
extracting docstrings and transforming them into documentation in
standard formats (e.g., HTML, DocBook, TeX). There have been a
number of proposed markup formats and variations, and many tools
tied to these proposals, but without a standard docstring format
they have failed to gain a strong following and/or floundered
half-finished.
The adoption of a standard will, at the very least, benefit
docstring processing tools by preventing further "reinventing the
wheel".
The lack of a standard syntax for docstrings has hampered the
development of standard tools for extracting and converting
docstrings into documentation in standard formats (e.g., HTML,
DocBook, TeX). There have been a number of proposed markup
formats and variations, and many tools tied to these proposals,
but without a standard docstring format they have failed to gain a
strong following and/or floundered half-finished.
Throughout the existence of the Doc-SIG, consensus on a single
standard docstring format has never been reached. A lightweight,
@ -118,12 +166,12 @@ Rationale
others):
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.
2. Programmers want to add structure to their docstrings, without
sacrificing raw docstring readability. Unadorned plaintext
cannot be transformed ('up-translated') into useful structured
cannot be transformed ("up-translated") into useful structured
formats.
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
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 and SGML are explicit, well-formed meta-languages suitable
for all kinds of documentation. XML is a variant of SGML. They
are best used behind the scenes, because they are verbose,
difficult to type, and too cluttered to read comfortably as
source. DocBook, HTML, and XHTML are all applications of SGML
and/or XML, and all share the same basic syntax and the same
shortcomings.
are best used behind the scenes, because to untrained eyes they
are verbose, difficult to type, and too cluttered to read
comfortably as source. DocBook, HTML, and XHTML are all
applications of SGML and/or XML, and all share the same basic
syntax and the same shortcomings.
- TeX [8]_
TeX is similar to XML/SGML in that it's explicit, not very easy
to write, and not easy for the uninitiated to read.
TeX is similar to XML/SGML in that it's explicit, but not very
easy to write, and not easy for the uninitiated to read.
- Perl POD [9]_
Most Perl modules are documented in a format called POD -- Plain
Old Documentation. This is an easy-to-type, very low level
Most Perl modules are documented in a format called POD (Plain
Old Documentation). This is an easy-to-type, very low level
format with strong integration with the Perl parser. Many tools
exist to turn POD documentation into other formats: info, HTML
and man pages, among others. However, the POD syntax takes
@ -163,17 +216,16 @@ Rationale
Special comments before Java classes and functions serve to
document the code. A program to extract these, and turn them
into HTML documentation is called javadoc, and is part of the
standard Java distribution. However, the only output format
that is supported is HTML, and JavaDoc has a very intimate
relationship with HTML, using HTML tags for most markup. Thus
it shares the readability problems of HTML.
standard Java distribution. However, JavaDoc has a very
intimate relationship with HTML, using HTML tags for most
markup. Thus it shares the readability problems of HTML.
- Setext [11]_, StructuredText [12]_
Early on, variants of Setext (Structure Enhanced Text),
including Zope Corp's StructuredText, were proposed for Python
docstring formatting. Hereafter these variants will
collectively be 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
easy to write.
@ -188,7 +240,8 @@ Rationale
requirements.
- 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.
@ -198,6 +251,7 @@ Rationale
- There has been no mechanism to get around the SText markup
rules when a markup character is used in a non-markup context.
In other words, no way to escape markup.
Proponents of implicit STexts have vigorously opposed proposals
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.
Features
Specification
Rather than repeating or summarizing the extensive
reStructuredText spec, please read the originals available from
http://structuredtext.sourceforge.net/spec/ (.txt & .html files).
Reading the documents in following order is recommended:
The specification and user documentaton for reStructuredText is
quite extensive. Rather than repeating or summarizing it all
here, links to the originals are provided.
- 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
StructuredText; it explains many markup decisions made)
- An Introduction to reStructuredText [15]_
- reStructuredText Markup Specification [15]_
- A Record of reStructuredText Syntax Alternatives [16]_ (explains
markup decisions made independently of StructuredText)
- reStructuredText Markup Specification [16]_
- 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.
@ -288,6 +344,8 @@ Features
class Keeper(Storer):
"""
Keep data fresher longer.
Extend `Storer`. Class attribute `instances` keeps track
of the number of `Keeper` objects instantiated.
"""
@ -340,9 +398,10 @@ Features
These are mostly used for extension syntax, such as
"bibliographic field lists" (representing document metadata such
as author, date, and version) and extension attributes for
directives (see below). They may be used to implement docstring
semantics, such as identifying parameters, exceptions raised,
etc.; such usage is beyond the scope of this PEP.
directives (see below). They may be used to implement
methodologies (docstring semantics), such as identifying
parameters, exceptions raised, etc.; such usage is beyond the
scope of this PEP.
A modified RFC 2822 syntax is used, with a colon *before* as
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
construct because it is ambiguous. A word followed by a colon
at the beginning of a line is common in written text. However,
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.
at the beginning of a line is common in written text.
- Markup extensibility: directives and substitutions.
@ -381,7 +436,7 @@ Features
The |biohazard| symbol must be used on containers used to
dispose of medical waste.
.. |biohazard| image:: biohazard.png
- Section structure markup.
@ -405,25 +460,26 @@ Features
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
require for a specific application, it can be added via the
directive mechanism. If a common construct has been
Yes, it is for most people. If it lacks some construct that is
required for a specific application, it can be added via the
directive mechanism. If a useful and common construct has been
overlooked and a suitably readable syntax can be found, it can
be added to the specification and parser.
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
proposed on the Doc-SIG, someone has complained about the lack
of support for some construct or other. The reply was often
something like, "These are docstrings we're talking about, and
docstrings shouldn't have complex markup." The problem is that
a construct that seems superfluous to one person may be
absolutely essential to another.
Since the very beginning, whenever a docstring markup syntax
has been proposed on the Doc-SIG, someone has complained about
the lack of support for some construct or other. The reply was
often something like, "These are docstrings we're talking
about, and docstrings shouldn't have complex markup." The
problem is that a construct that seems superfluous to one
person may be absolutely essential to another.
reStructuredText takes the opposite approach: it provides a
rich set of implicit markup constructs (plus a generic
@ -433,10 +489,10 @@ Questions & Answers
removed from the parser (via application-specific overrides) or
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"?
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:
I still think that using indentation to indicate sectioning
@ -455,20 +511,20 @@ Questions & Answers
over 30 centuries. Let's not innovate needlessly.
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?
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
for such a reference-rich document type. PEPs are currently
converted into HTML, but the results (mostly monospaced text)
are less than attractive, and most of the value-added potential
of HTML is untapped.
of HTML (especially inline hyperlinks) is untapped.
Making reStructuredText the standard markup for PEPs will
enable much richer expression, including support for section
Making reStructuredText a standard markup for PEPs will enable
much richer expression, including support for section
structure, inline markup, graphics, and tables. In several
PEPs there are ASCII graphics diagrams, which are all that
plaintext documents can support. Since PEPs are made available
@ -497,13 +553,13 @@ Questions & Answers
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]
mechanism.
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
http://www.python.org/peps/pep-9876.html
@ -518,16 +574,17 @@ Questions & Answers
Abstract
========
This PEP proposes a adding `frungible doodads`_ to the
core. It extends PEP 9876 [#pep9876] via the BCA [#]
mechanism.
This PEP proposes adding `frungible doodads`_ to the core.
It extends PEP 9876 [#pep9876]_ via the BCA [#]_ 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"
@ -543,7 +600,7 @@ Questions & Answers
URL references can be named ("frungible doodads"), and can be
referenced from multiple places in the document without
additional definitions. When converted to HTML, references
will be replaced with inline hyperlinks (HTML <A> tags). The
will be replaced with inline hyperlinks (HTML <a> tags). The
two footnotes are automatically numbered, so they will always
stay in sync. The first footnote also contains an internal
reference name, "pep9876", so it's easier to see the connection
@ -556,54 +613,123 @@ Questions & Answers
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
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?
A: The PEP markup proposal is an option to this PEP. It may be
removed if it is deemed that there is no need for PEP markup.
The PEP markup proposal could be made into a separate PEP if
necessary. If accepted, PEP 1, PEP Purpose and Guidelines [19]_,
and PEP 9, Sample PEP Template [20]_ will be updated.
The PEP markup proposal may be removed if it is deemed that
there is no need for PEP markup, or it could be made into a
separate PEP. If accepted, PEP 1, PEP Purpose and Guidelines
[20]_, and PEP 9, Sample PEP Template [21]_ will be updated.
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
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
parsing. The Docutils project will support PEPs with a "PEP
Reader" component, including all functionality currently in
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
greater Python communities. If insufficient volunteers are
forthcoming, I (David Goodger) will convert the documents
myself, perhaps with some level of automation. A transitional
system whereby both old and new standards can coexist will be
easy to implement (and I pledge to implement it if necessary).
PEP authors or volunteers may convert existing PEPs if they
like, but there is no requirement to do so. The
reStructuredText-based PEPs will coexist with the old PEP
standard. The pep2html.py mentioned in answer 6 will process
both old and new standards.
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
other ancillary files. By adopting a standard markup, these
files can be converted to attractive cross-referenced HTML and
put up on python.org. Developers of Python projects can also
take advantage of this facility for their own documentation.
The reasoning given for PEPs in answer 4 above also applies to
README and other ancillary files. By adopting a standard
markup, these files can be converted to attractive
cross-referenced HTML and put up on python.org. Developers of
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/
@ -627,33 +753,40 @@ References and Footnotes
[12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
[13] An Introduction to reStructuredText
http://structuredtext.sourceforge.net/spec/introduction.txt
[13] A ReStructuredText Primer
http://docutils.sourceforge.net/docs/rst/quickstart.html
[14] Problems with StructuredText
http://structuredtext.sourceforge.net/spec/problems.txt
[14] Quick reStructuredText
http://docutils.sourceforge.net/docs/rst/quickref.html
[15] reStructuredText Markup Specification
http://structuredtext.sourceforge.net/spec/reStructuredText.txt
[15] An Introduction to reStructuredText
http://docutils.sourceforge.net/spec/rst/introduction.html
[16] A Record of reStructuredText Syntax Alternatives
http://structuredtext.sourceforge.net/spec/alternatives.txt
[16] reStructuredText Markup Specification
http://docutils.sourceforge.net/spec/rst/reStructuredText.html
[17] reStructuredText Directives
http://structuredtext.sourceforge.net/spec/directives.txt
http://docutils.sourceforge.net/spec/rst/directives.html
[18] Quick reStructuredText
http://structuredtext.sourceforge.net/docs/quickref.html
[18] Problems with StructuredText
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
[20] PEP 9, Sample PEP Template, Warsaw
[21] PEP 9, Sample PEP Template, Warsaw
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
@ -664,10 +797,11 @@ Copyright
Acknowledgements
Some text is borrowed from PEP 216, Docstring Format, by Moshe
Zadka [22]_.
Some text is borrowed from PEP 216, Docstring Format [24]_, by
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.