[Python-checkins] python/nondist/peps pep-0256.txt,1.3,1.4 pep-0257.txt,1.5,1.6 pep-0258.txt,1.3,1.4 pep-0287.txt,1.3,1.4
goodger@users.sourceforge.net
goodger@users.sourceforge.net
Thu, 29 Aug 2002 20:10:54 -0700
Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv30789
Modified Files:
pep-0256.txt pep-0257.txt pep-0258.txt pep-0287.txt
Log Message:
Converted to reStructuredText & updated.
Index: pep-0256.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0256.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0256.txt 1 Aug 2002 22:32:33 -0000 1.3
--- pep-0256.txt 30 Aug 2002 03:10:51 -0000 1.4
***************
*** 3,10 ****
Version: $Revision$
Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger)
! Discussions-To: doc-sig@python.org
Status: Draft
Type: Standards Track
Created: 01-Jun-2001
Post-History: 13-Jun-2001
--- 3,11 ----
Version: $Revision$
Last-Modified: $Date$
! 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
***************
*** 12,291 ****
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.
! 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.
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 [6]_
! - Daniel Larsson's pythondoc & gendoc [7]_
! - Doug Hellmann's HappyDoc [8]_
! - Laurence Tratt's Crystal [9]_
! - Ka-Ping Yee's htmldoc & pydoc [10]_ (pydoc.py is now part of the
! Python standard library; see below)
! - 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 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.
! 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:
! - 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. 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.
Specification
! The docstring processing system framework consists of components,
! as follows::
! 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.
! 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.
! - Docstring extraction rules.
! - Readers, which encapsulate the input context .
! - 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.
! - 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, Docutils Design Specification [13 ]_,
! documents these issues.
! 3. Docstring processing system implementation.
! 4. Input markup specifications: docstring syntax. PEP 287,
! reStructuredText Docstring Format [15]_, proposes a standard
! syntax.
! 5. Input parser 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
! stylists which allow for a variety of output document styles.
! 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.
Project Web Site
! A SourceForge project has been set up for this work at
! http://docutils.sourceforge.net/.
References and Footnotes
! [1] http://www.literateprogramming.com/
! [2] Perl "Plain Old Documentation"
! http://www.perldoc.com/perl5.6/pod/perlpod.html
! [3] http://java.sun.com/j2se/javadoc/
! [4] http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
! [5] http://www-cs-faculty.stanford.edu/~knuth/cweb.html
! [6] http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
! [7] http://starship.python.net/crew/danilo/pythondoc/
! [8] http://happydoc.sourceforge.net/
! [9] http://www.btinternet.com/~tratt/comp/python/crystal/
! [10] http://www.python.org/doc/current/lib/module-pydoc.html
! [11] http://homepage.ntlworld.com/tibsnjoan/docutils/
! [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
! [15] PEP 287, reStructuredText Docstring Format, Goodger
! http://www.python.org/peps/pep-0287.html
! [16] http://www.python.org/sigs/doc-sig/
Copyright
! 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.
! Local Variables:
! mode: indented-text
! indent-tabs-mode: nil
! fill-column: 70
! sentence-end-double-space: t
! End:
--- 13,299 ----
Abstract
+ ========
! 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 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"
! [#PEP-287]_, 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" [#PEP-257]_.
! - Methodology: rules for the informational content of docstrings.
! Not addressed.
! * 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.
! 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_ ("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):
! - Marc-Andre Lemburg's doc.py_
! - Daniel Larsson's pythondoc_ & gendoc_
! - Doug Hellmann's HappyDoc_
! - Laurence Tratt's Crystal_
! - Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard
! library; see below)
! - Tony Ibbs' docutils_ (Tony has donated this name to the `Docutils
! project`_)
! - 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.
! 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.
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:
! - 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 [#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.
! 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 is broken up as follows:
! 1. Docstring conventions. Documents issues such as:
! - What should be documented where.
! - First line is a one-line synopsis.
! PEP 257 [#PEP-257]_ documents some of these issues.
! 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.
! - Docstring extraction rules.
! - Readers, which encapsulate the input context .
! - 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.
! - 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 [#PEP-258]_ documents these issues.
! 3. Docstring processing system implementation.
! 4. Input markup specifications: docstring syntax. PEP 287 [#PEP-287]_
! proposes a standard syntax.
! 5. Input parser 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
! stylists which allow for a variety of output document styles.
! 8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
! implementations.
! 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/.
References and Footnotes
+ ========================
! .. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger
! (http://www.python.org/peps/pep-0287.html)
! .. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum
! (http://www.python.org/peps/pep-0257.html)
! .. [#PEP-258] PEP 258, Docutils Design Specification, Goodger
! (http://www.python.org/peps/pep-0258.html)
! .. _Literate Programming: http://www.literateprogramming.com/
! .. _POD: http://www.perldoc.com/perl5.6/pod/perlpod.html
! .. _Javadoc: http://java.sun.com/j2se/javadoc/
! .. _Autoduck:
! http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
! .. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html
! .. _doc.py:
! http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
! .. _pythondoc:
! .. _gendoc: http://starship.python.net/crew/danilo/pythondoc/
! .. _HappyDoc: http://happydoc.sourceforge.net/
! .. _Crystal: http://www.btinternet.com/~tratt/comp/python/crystal/
! .. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html
! .. _docutils: http://homepage.ntlworld.com/tibsnjoan/docutils/
! .. _Docutils project: http://docutils.sourceforge.net/
! .. _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.
Acknowledgements
+ ================
! 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
! sentence-end-double-space: t
! fill-column: 70
! End:
Index: pep-0257.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0257.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** pep-0257.txt 1 Aug 2002 22:32:33 -0000 1.5
--- pep-0257.txt 30 Aug 2002 03:10:51 -0000 1.6
***************
*** 3,11 ****
Version: $Revision$
Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger),
! guido@python.org (Guido van Rossum)
Discussions-To: doc-sig@python.org
Status: Active
Type: Informational
Created: 29-May-2001
Post-History: 13-Jun-2001
--- 3,12 ----
Version: $Revision$
Last-Modified: $Date$
! 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
***************
*** 13,256 ****
Abstract
! 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.
! "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
! 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.
Specification
! 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.
! 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:
! 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".
! 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. For Unicode docstrings, use
! u"""Unicode triple-quoted strings""".
! 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::
! def kos_root():
! """Return the pathname of the KOS root directory."""
! global _kos_root
! if _kos_root: return _kos_root
! ...
! Notes:
! - 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.
! - 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 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::
! 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.
! 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.
! 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 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 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 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 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.
! 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.
! 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
! ...
! 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
! [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] http://www.python.org/doc/essays/styleguide.html
! [5] http://www.python.org/sigs/doc-sig/
Copyright
! 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].
! This document borrows ideas from the archives of the Python
! Doc-SIG [5]. 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:
--- 14,263 ----
Abstract
+ ========
! 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.
! "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
! 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?
! --------------------
! 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.
! 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".
! 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.
! 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"""``.
! 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::
! def kos_root():
! """Return the pathname of the KOS root directory."""
! global _kos_root
! if _kos_root: return _kos_root
! ...
! Notes:
! - 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.
! - 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 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::
! 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.
! 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.
! 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 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 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 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 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.
! 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.
! 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
! ...
!
! 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)
! .. [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.
! .. _Docutils: http://docutils.sourceforge.net/
! .. _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.
Acknowledgements
+ ================
! 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_.
! 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:
Index: pep-0258.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0258.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0258.txt 1 Aug 2002 22:32:33 -0000 1.3
--- pep-0258.txt 30 Aug 2002 03:10:51 -0000 1.4
***************
*** 3,10 ****
Version: $Revision$
Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger)
! Discussions-To: doc-sig@python.org
Status: Draft
Type: Standards Track
Requires: 256, 257
Created: 31-May-2001
--- 3,11 ----
Version: $Revision$
[...1821 lines suppressed...]
! This document has been placed in the public domain.
! ==================
! Acknowledgements
! ==================
! 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
! sentence-end-double-space: t
! fill-column: 70
! End:
Index: pep-0287.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0287.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0287.txt 1 Aug 2002 22:32:33 -0000 1.3
--- pep-0287.txt 30 Aug 2002 03:10:51 -0000 1.4
***************
*** 3,10 ****
Version: $Revision$
Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger)
! Discussions-To: doc-sig@python.org
Status: Draft
Type: Informational
Created: 25-Mar-2002
Post-History: 02-Apr-2002
--- 3,11 ----
Version: $Revision$
[...1594 lines suppressed...]
! This document has been placed in the public domain.
Acknowledgements
+ ================
! Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by
! Moshe Zadka.
! Special thanks to all members past & present of the Python Doc-SIG_.
! ..
! Local Variables:
! mode: indented-text
! indent-tabs-mode: nil
! sentence-end-double-space: t
! fill-column: 70
! End: