Converted to reStructuredText & updated.
This commit is contained in:
David Goodger
parent
2bba139678
commit
dde379d684
338
pep-0256.txt
338
pep-0256.txt
|
|
@ -2,177 +2,178 @@ PEP: 256
|
|||
Title: Docstring Processing System Framework
|
||||
Version: $Revision$
|
||||
Last-Modified: $Date$
|
||||
Author: goodger@users.sourceforge.net (David Goodger)
|
||||
Discussions-To: doc-sig@python.org
|
||||
Author: David Goodger <goodger@users.sourceforge.net>
|
||||
Discussions-To: <doc-sig@python.org>
|
||||
Status: Draft
|
||||
Type: Standards Track
|
||||
Content-Type: text/x-rst
|
||||
Created: 01-Jun-2001
|
||||
Post-History: 13-Jun-2001
|
||||
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
||||
Python lends itself to inline documentation. With its built-in
|
||||
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.
|
||||
Python lends itself to inline documentation. With its built-in
|
||||
docstring syntax, a limited form of `Literate Programming`_ 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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
The concepts of a DPS framework are presented independently of
|
||||
implementation details.
|
||||
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:
|
||||
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 syntax. PEP 287, "reStructuredText Docstring Format"
|
||||
[#PEP-287]_, proposes a syntax for Python docstrings, PEPs, and
|
||||
other uses.
|
||||
|
||||
* Docstring semantics consist of at least two aspects:
|
||||
* Docstring semantics consist of at least two aspects:
|
||||
|
||||
- Conventions: the high-level structure of docstrings. Dealt
|
||||
with in PEP 257, Docstring Conventions.
|
||||
- Conventions: the high-level structure of docstrings. Dealt with
|
||||
in PEP 257, "Docstring Conventions" [#PEP-257]_.
|
||||
|
||||
- Methodology: rules for the informational content of
|
||||
docstrings. Not addressed.
|
||||
- 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.
|
||||
* Processing mechanisms. This PEP (PEP 256) outlines the high-level
|
||||
issues and specification of an abstract docstring processing system
|
||||
(DPS). PEP 258, "Docutils Design Specification" [#PEP-258]_, 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.
|
||||
* 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.
|
||||
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 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 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_ and Web_ (Tangle & Weave), useful for multiple languages.
|
||||
|
||||
There have been many attempts to write auto-documentation systems
|
||||
for Python (not an exhaustive list):
|
||||
There have been many attempts to write auto-documentation systems
|
||||
for Python (not an exhaustive list):
|
||||
|
||||
- Marc-Andre Lemburg's doc.py [6]_
|
||||
- Marc-Andre Lemburg's doc.py_
|
||||
|
||||
- Daniel Larsson's pythondoc & gendoc [7]_
|
||||
- Daniel Larsson's pythondoc_ & gendoc_
|
||||
|
||||
- Doug Hellmann's HappyDoc [8]_
|
||||
- Doug Hellmann's HappyDoc_
|
||||
|
||||
- Laurence Tratt's Crystal [9]_
|
||||
- Laurence Tratt's Crystal_
|
||||
|
||||
- Ka-Ping Yee's htmldoc & pydoc [10]_ (pydoc.py is now part of the
|
||||
Python standard library; see below)
|
||||
- Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard
|
||||
library; see below)
|
||||
|
||||
- Tony Ibbs' docutils [11]_
|
||||
- Tony Ibbs' docutils_ (Tony has donated this name to the `Docutils
|
||||
project`_)
|
||||
|
||||
- Edward Loper's STminus formalization and related efforts [12]_
|
||||
- Edward Loper's STminus_ formalization and related efforts
|
||||
|
||||
These systems, each with different goals, have had varying degrees
|
||||
of success. A problem with many of the above systems was
|
||||
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.
|
||||
These systems, each with different goals, have had varying degrees of
|
||||
success. A problem with many of the above systems was 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 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.
|
||||
It has become clear (to this author, at least) that the "all or
|
||||
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, either merged from existing systems, and/or developed
|
||||
anew. This system should be included in Python's standard
|
||||
library.
|
||||
Each of the components of a docstring processing system should be
|
||||
developed independently. A "best of breed" system should be 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 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:
|
||||
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.
|
||||
- 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.
|
||||
- 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 [#PEP-258]_), and the order of definitions.
|
||||
|
||||
The functionality proposed in this PEP could be added to or used
|
||||
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.
|
||||
The functionality proposed in this PEP could be added to or used 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.
|
||||
However, if this framework is accepted and adopted as the Python
|
||||
standard, compatibility will become an important consideration in
|
||||
these systems' future.
|
||||
Similarly for other existing docstring processing systems, their
|
||||
authors may or may not choose compatibility with this framework.
|
||||
However, if this framework is accepted and adopted as the Python
|
||||
standard, compatibility will become an important consideration in
|
||||
these systems' future.
|
||||
|
||||
|
||||
Specification
|
||||
=============
|
||||
|
||||
The docstring processing system framework consists of components,
|
||||
as follows::
|
||||
The docstring processing system framework is broken up as follows:
|
||||
|
||||
1. Docstring conventions. Documents issues such as:
|
||||
1. Docstring conventions. Documents issues such as:
|
||||
|
||||
- What should be documented where.
|
||||
|
||||
- First line is a one-line synopsis.
|
||||
|
||||
PEP 257, Docstring Conventions [14]_, documents some of these
|
||||
issues.
|
||||
PEP 257 [#PEP-257]_ documents some of these issues.
|
||||
|
||||
2. Docstring processing system design specification. Documents
|
||||
2. Docstring processing system design specification. Documents
|
||||
issues such as:
|
||||
|
||||
- High-level spec: what a DPS does.
|
||||
|
|
@ -188,8 +189,8 @@ Specification
|
|||
- Parsers.
|
||||
|
||||
- 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 of the Parser and Reader, and the input to the Writer all
|
||||
share the same data structure.
|
||||
|
||||
- Transforms, which modify the document tree.
|
||||
|
||||
|
|
@ -199,93 +200,100 @@ Specification
|
|||
files, or objects in memory).
|
||||
|
||||
These issues are applicable to any docstring processing system
|
||||
implementation. PEP 258, Docutils Design Specification [13 ]_,
|
||||
documents these issues.
|
||||
implementation. PEP 258 [#PEP-258]_ documents these issues.
|
||||
|
||||
3. Docstring processing system implementation.
|
||||
3. Docstring processing system implementation.
|
||||
|
||||
4. Input markup specifications: docstring syntax. PEP 287,
|
||||
reStructuredText Docstring Format [15]_, proposes a standard
|
||||
syntax.
|
||||
4. Input markup specifications: docstring syntax. PEP 287 [#PEP-287]_
|
||||
proposes a standard syntax.
|
||||
|
||||
5. Input parser implementations.
|
||||
5. Input parser implementations.
|
||||
|
||||
6. Input context readers ("modes": Python source code, PEP,
|
||||
standalone text file, email, etc.) and implementations.
|
||||
6. Input context readers ("modes": Python source code, PEP, standalone
|
||||
text file, email, etc.) and implementations.
|
||||
|
||||
7. Stylists: certain input context readers may have associated
|
||||
7. Stylists: certain input context readers may have associated
|
||||
stylists which allow for a variety of output document styles.
|
||||
|
||||
8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
|
||||
8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
|
||||
implementations.
|
||||
|
||||
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.
|
||||
Components 1, 2/3/5, and 4 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://docutils.sourceforge.net/.
|
||||
A SourceForge project has been set up for this work at
|
||||
http://docutils.sourceforge.net/.
|
||||
|
||||
|
||||
References and Footnotes
|
||||
========================
|
||||
|
||||
[1] http://www.literateprogramming.com/
|
||||
.. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger
|
||||
(http://www.python.org/peps/pep-0287.html)
|
||||
|
||||
[2] Perl "Plain Old Documentation"
|
||||
http://www.perldoc.com/perl5.6/pod/perlpod.html
|
||||
.. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum
|
||||
(http://www.python.org/peps/pep-0257.html)
|
||||
|
||||
[3] http://java.sun.com/j2se/javadoc/
|
||||
.. [#PEP-258] PEP 258, Docutils Design Specification, Goodger
|
||||
(http://www.python.org/peps/pep-0258.html)
|
||||
|
||||
[4] http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
|
||||
.. _Literate Programming: http://www.literateprogramming.com/
|
||||
|
||||
[5] http://www-cs-faculty.stanford.edu/~knuth/cweb.html
|
||||
.. _POD: http://www.perldoc.com/perl5.6/pod/perlpod.html
|
||||
|
||||
[6] http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
|
||||
.. _Javadoc: http://java.sun.com/j2se/javadoc/
|
||||
|
||||
[7] http://starship.python.net/crew/danilo/pythondoc/
|
||||
.. _Autoduck:
|
||||
http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
|
||||
|
||||
[8] http://happydoc.sourceforge.net/
|
||||
.. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html
|
||||
|
||||
[9] http://www.btinternet.com/~tratt/comp/python/crystal/
|
||||
.. _doc.py:
|
||||
http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
|
||||
|
||||
[10] http://www.python.org/doc/current/lib/module-pydoc.html
|
||||
.. _pythondoc:
|
||||
.. _gendoc: http://starship.python.net/crew/danilo/pythondoc/
|
||||
|
||||
[11] http://homepage.ntlworld.com/tibsnjoan/docutils/
|
||||
.. _HappyDoc: http://happydoc.sourceforge.net/
|
||||
|
||||
[12] http://www.cis.upenn.edu/~edloper/pydoc/
|
||||
.. _Crystal: http://www.btinternet.com/~tratt/comp/python/crystal/
|
||||
|
||||
[13] PEP 258, Docutils Design Specification, Goodger
|
||||
http://www.python.org/peps/pep-0258.html
|
||||
.. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html
|
||||
|
||||
[14] PEP 257, Docstring Conventions, Goodger, Van Rossum
|
||||
http://www.python.org/peps/pep-0257.html
|
||||
.. _docutils: http://homepage.ntlworld.com/tibsnjoan/docutils/
|
||||
|
||||
[15] PEP 287, reStructuredText Docstring Format, Goodger
|
||||
http://www.python.org/peps/pep-0287.html
|
||||
.. _Docutils project: http://docutils.sourceforge.net/
|
||||
|
||||
[16] http://www.python.org/sigs/doc-sig/
|
||||
.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/
|
||||
|
||||
.. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/
|
||||
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
This document has been placed in the public domain.
|
||||
This document has been placed in the public domain.
|
||||
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
|
||||
This document borrows ideas from the archives of the Python
|
||||
Doc-SIG [16]_. Thanks to all members past & present.
|
||||
This document borrows ideas from the archives of the `Python
|
||||
Doc-SIG`_. Thanks to all members past & present.
|
||||
|
||||
|
||||
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
fill-column: 70
|
||||
sentence-end-double-space: t
|
||||
End:
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
sentence-end-double-space: t
|
||||
fill-column: 70
|
||||
End:
|
||||
|
|
|
|||
319
pep-0257.txt
319
pep-0257.txt
|
|
@ -2,87 +2,92 @@ PEP: 257
|
|||
Title: Docstring Conventions
|
||||
Version: $Revision$
|
||||
Last-Modified: $Date$
|
||||
Author: goodger@users.sourceforge.net (David Goodger),
|
||||
guido@python.org (Guido van Rossum)
|
||||
Author: David Goodger <goodger@users.sourceforge.net>,
|
||||
Guido van Rossum <guido@python.org>
|
||||
Discussions-To: doc-sig@python.org
|
||||
Status: Active
|
||||
Type: Informational
|
||||
Content-Type: text/x-rst
|
||||
Created: 29-May-2001
|
||||
Post-History: 13-Jun-2001
|
||||
|
||||
|
||||
Abstract
|
||||
========
|
||||
|
||||
This PEP documents the semantics and conventions associated with
|
||||
Python docstrings.
|
||||
This PEP documents the semantics and conventions associated with
|
||||
Python docstrings.
|
||||
|
||||
|
||||
Rationale
|
||||
=========
|
||||
|
||||
The aim of this PEP is to standardize the high-level structure of
|
||||
docstrings: what they should contain, and how to say it (without
|
||||
touching on any markup syntax within docstrings). The PEP
|
||||
contains conventions, not laws or syntax.
|
||||
The aim of this PEP is to standardize the high-level structure of
|
||||
docstrings: what they should contain, and how to say it (without
|
||||
touching on any markup syntax within docstrings). The PEP contains
|
||||
conventions, not laws or syntax.
|
||||
|
||||
"A universal convention supplies all of maintainability,
|
||||
clarity, consistency, and a foundation for good programming
|
||||
habits too. What it doesn't do is insist that you follow it
|
||||
against your will. That's Python!"
|
||||
"A universal convention supplies all of maintainability, clarity,
|
||||
consistency, and a foundation for good programming habits too.
|
||||
What it doesn't do is insist that you follow it against your will.
|
||||
That's Python!"
|
||||
|
||||
--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
|
||||
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.
|
||||
If you violate these conventions, the worst you'll get is some dirty
|
||||
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
|
||||
=============
|
||||
|
||||
What is a Docstring?
|
||||
--------------------
|
||||
What is a Docstring?
|
||||
--------------------
|
||||
|
||||
A docstring is a string literal that occurs as the first statement
|
||||
in a module, function, class, or method definition. Such a
|
||||
docstring becomes the __doc__ special attribute of that object.
|
||||
A docstring is a string literal that occurs as the first statement 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
|
||||
classes exported by a module should also have docstrings. Public
|
||||
methods (including the __init__ constructor) should also have
|
||||
docstrings. A package may be documented in the module docstring
|
||||
of the __init__.py file in the package directory.
|
||||
All modules should normally have docstrings, and all functions and
|
||||
classes exported by a module should also have docstrings. Public
|
||||
methods (including the ``__init__`` constructor) should also have
|
||||
docstrings. A package may be documented in the module docstring of
|
||||
the ``__init__.py`` file in the package directory.
|
||||
|
||||
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
|
||||
may be extracted by software tools:
|
||||
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 may be
|
||||
extracted by software tools:
|
||||
|
||||
1. String literals occurring immediately after a simple assignment
|
||||
at the top level of a module, class, or __init__ method
|
||||
are called "attribute docstrings".
|
||||
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 occurring immediately after another docstring
|
||||
are called "additional docstrings".
|
||||
2. String literals occurring immediately after another docstring are
|
||||
called "additional docstrings".
|
||||
|
||||
Please see PEP 258 "Docutils Design Specification" [2] for a
|
||||
detailed description of attribute and additional docstrings.
|
||||
Please see PEP 258, "Docutils Design Specification" [2]_, for a
|
||||
detailed description of attribute and additional docstrings.
|
||||
|
||||
XXX Mention docstrings of 2.2 properties.
|
||||
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. For Unicode docstrings, use
|
||||
u"""Unicode triple-quoted strings""".
|
||||
For consistency, always use ``"""triple double quotes"""`` around
|
||||
docstrings. Use ``r"""raw triple double quotes"""`` if you use any
|
||||
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.
|
||||
There are two forms of docstrings: one-liners and multi-line
|
||||
docstrings.
|
||||
|
||||
One-line Docstrings
|
||||
--------------------
|
||||
|
||||
One-liners are for really obvious cases. They should really fit
|
||||
on one line. For example::
|
||||
One-line Docstrings
|
||||
--------------------
|
||||
|
||||
One-liners are for really obvious cases. They should really fit on
|
||||
one line. For example::
|
||||
|
||||
def kos_root():
|
||||
"""Return the pathname of the KOS root directory."""
|
||||
|
|
@ -90,115 +95,110 @@ Specification
|
|||
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.
|
||||
|
||||
- The closing quotes are on the same line as the opening quotes.
|
||||
This looks better for one-liners.
|
||||
- The closing quotes are on the same line as the opening quotes. This
|
||||
looks better for one-liners.
|
||||
|
||||
- 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
|
||||
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 docstring is a phrase ending in a period. It prescribes the
|
||||
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/method parameters (which can be obtained by
|
||||
introspection). Don't do::
|
||||
- The one-line docstring should NOT be a "signature" reiterating 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. 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::
|
||||
This type of docstring is only appropriate for C functions (such 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 consist of a summary line just like a
|
||||
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. The
|
||||
summary line may be on the same line as the opening quotes or on
|
||||
the next line.
|
||||
Multi-line Docstrings
|
||||
----------------------
|
||||
|
||||
The entire docstring is indented the same as the quotes at its
|
||||
first line (see example below). Docstring processing tools will
|
||||
strip an amount of indentation from the second and further lines
|
||||
of the docstring equal to the indentation of the first non-blank
|
||||
line after the first line of the docstring. Relative indentation
|
||||
of later lines in the docstring is retained.
|
||||
Multi-line docstrings consist of a summary line just like a 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. The summary line may be on
|
||||
the same line as the opening quotes or on the next line.
|
||||
|
||||
Insert a blank line before and after all docstrings (one-line or
|
||||
multi-line) that document a class -- generally speaking, the
|
||||
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 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 entire docstring is indented the same as the quotes at its first
|
||||
line (see example below). Docstring processing tools will strip an
|
||||
amount of indentation from the second and further lines of the
|
||||
docstring equal to the indentation of the first non-blank line after
|
||||
the first line of the docstring. Relative indentation of later lines
|
||||
in the docstring is retained.
|
||||
|
||||
The docstring of a script (a stand-alone program) should be usable
|
||||
as its "usage" message, printed when the script is invoked with
|
||||
incorrect or missing arguments (or perhaps with a "-h" option, for
|
||||
"help"). Such a docstring should document the script's function
|
||||
and command line syntax, environment variables, and files. Usage
|
||||
messages can be fairly elaborate (several screens full) and should
|
||||
be sufficient for a new user to use the command properly, as well
|
||||
as a complete quick reference to all options and arguments for the
|
||||
sophisticated user.
|
||||
Insert a blank line before and after all docstrings (one-line or
|
||||
multi-line) that document a class -- generally speaking, the 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 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 for a module should generally list the classes,
|
||||
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
|
||||
the package's __init__.py module) should also list the modules and
|
||||
subpackages exported by the package.
|
||||
The docstring of a script (a stand-alone program) should be usable as
|
||||
its "usage" message, printed when the script is invoked with incorrect
|
||||
or missing arguments (or perhaps with a "-h" option, for "help").
|
||||
Such a docstring should document the script's function and command
|
||||
line syntax, environment variables, and files. Usage messages can be
|
||||
fairly elaborate (several screens full) and should be sufficient for a
|
||||
new user to use the command properly, as well as a complete quick
|
||||
reference to all options and arguments for the sophisticated user.
|
||||
|
||||
The docstring for a function or method should summarize its
|
||||
behavior and document its arguments, return value(s), side
|
||||
effects, exceptions raised, and restrictions on when it can be
|
||||
called (all if applicable). Optional arguments should be
|
||||
indicated. It should be documented whether keyword arguments are
|
||||
part of the interface.
|
||||
The docstring for a module should generally list the classes,
|
||||
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 the
|
||||
package's ``__init__.py`` module) should also list the modules and
|
||||
subpackages exported by the package.
|
||||
|
||||
The docstring for a class should summarize its behavior and list
|
||||
the public methods and instance variables. If the class is
|
||||
intended to be subclassed, and has an additional interface for
|
||||
subclasses, this interface should be listed separately (in the
|
||||
docstring). The class constructor should be documented in the
|
||||
docstring for its __init__ method. Individual methods should be
|
||||
documented by their own docstring.
|
||||
The docstring for a function or method should summarize its behavior
|
||||
and document its arguments, return value(s), side effects, exceptions
|
||||
raised, and restrictions on when it can be called (all if applicable).
|
||||
Optional arguments should be indicated. It should be documented
|
||||
whether keyword arguments are part of the interface.
|
||||
|
||||
If a class subclasses another class and its behavior is mostly
|
||||
inherited from that class, its docstring should mention this and
|
||||
summarize the differences. Use the verb "override" to indicate
|
||||
that a subclass method replaces a superclass method and does not
|
||||
call the superclass method; use the verb "extend" to indicate that
|
||||
a subclass method calls the superclass method (in addition to its
|
||||
own behavior).
|
||||
The docstring for a class should summarize its behavior and list the
|
||||
public methods and instance variables. If the class is intended to be
|
||||
subclassed, and has an additional interface for subclasses, this
|
||||
interface should be listed separately (in the docstring). The class
|
||||
constructor should be documented in the docstring for its ``__init__``
|
||||
method. Individual methods should be documented by their own
|
||||
docstring.
|
||||
|
||||
*Do not* use the Emacs convention of mentioning the arguments of
|
||||
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
|
||||
example::
|
||||
If a class subclasses another class and its behavior is mostly
|
||||
inherited from that class, its docstring should mention this and
|
||||
summarize the differences. Use the verb "override" to indicate that a
|
||||
subclass method replaces a superclass method and does not call the
|
||||
superclass method; use the verb "extend" to indicate that a subclass
|
||||
method calls the superclass method (in addition to its own behavior).
|
||||
|
||||
*Do not* use the Emacs convention of mentioning the arguments of
|
||||
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 example::
|
||||
|
||||
def complex(real=0.0, imag=0.0):
|
||||
"""Form a complex number.
|
||||
|
|
@ -211,46 +211,53 @@ Specification
|
|||
if imag == 0.0 and real == 0.0: return complex_zero
|
||||
...
|
||||
|
||||
The BDFL [3] recommends inserting a blank line between the last
|
||||
paragraph in a multi-line docstring and its closing quotes,
|
||||
placing the closing quotes on a line by themselves. This way,
|
||||
Emacs' fill-paragraph command can be used on it.
|
||||
The BDFL [3]_ recommends inserting a blank line between the last
|
||||
paragraph in a multi-line docstring and its closing quotes, placing
|
||||
the closing quotes on a line by themselves. This way, Emacs'
|
||||
``fill-paragraph`` command can be used on it.
|
||||
|
||||
|
||||
References and Footnotes
|
||||
========================
|
||||
|
||||
[1] PEP 256, Docstring Processing System Framework, Goodger
|
||||
http://www.python.org/peps/pep-0256.html
|
||||
.. [1] PEP 256, Docstring Processing System Framework, Goodger
|
||||
(http://www.python.org/peps/pep-0256.html)
|
||||
|
||||
[2] PEP 258, Docutils Design Specification, Goodger
|
||||
http://www.python.org/peps/pep-0258.html
|
||||
.. [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
|
||||
.. [3] Guido van Rossum, Python's creator and Benevolent Dictator For
|
||||
Life.
|
||||
|
||||
[4] http://www.python.org/doc/essays/styleguide.html
|
||||
.. _Docutils: http://docutils.sourceforge.net/
|
||||
|
||||
[5] http://www.python.org/sigs/doc-sig/
|
||||
.. _Python Style Guide:
|
||||
http://www.python.org/doc/essays/styleguide.html
|
||||
|
||||
.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
|
||||
|
||||
|
||||
Copyright
|
||||
=========
|
||||
|
||||
This document has been placed in the public domain.
|
||||
This document has been placed in the public domain.
|
||||
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
|
||||
The "Specification" text comes mostly verbatim from the Python
|
||||
Style Guide essay by Guido van Rossum [4].
|
||||
The "Specification" text comes mostly verbatim from the `Python Style
|
||||
Guide`_ essay by Guido van Rossum.
|
||||
|
||||
This document borrows ideas from the archives of the Python
|
||||
Doc-SIG [5]. Thanks to all members past and present.
|
||||
This document borrows ideas from the archives of the Python Doc-SIG_.
|
||||
Thanks to all members past and present.
|
||||
|
||||
|
||||
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
fill-column: 70
|
||||
sentence-end-double-space: t
|
||||
End:
|
||||
..
|
||||
Local Variables:
|
||||
mode: indented-text
|
||||
indent-tabs-mode: nil
|
||||
fill-column: 70
|
||||
sentence-end-double-space: t
|
||||
End:
|
||||
|
|
|
|||
1003
pep-0258.txt
1003
pep-0258.txt
File diff suppressed because it is too large
Load Diff
990
pep-0287.txt
990
pep-0287.txt
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue