PEP 287 – reStructuredText Docstring Format | peps.python.org
PEP 287 – reStructuredText Docstring Format PEP 287 – reStructuredText Docstring Format Author : David Goodger <goodger at python.org> Discussions-To : Doc-SIG list Status : Active Type : Informational Created : 25-Mar-2002 Post-History : 02-Apr-2002 Replaces : 216 Table of Contents Abstract Benefits Goals Rationale Specification Docstring-Significant Features Questions & Answers Copyright Acknowledgements Abstract 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 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 (see PEP 256 for a “Road Map to the Docstring 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 ) 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 markup offers functionality and expressivity, while maintaining easy readability in the source text.
The processed form (HTML etc.) makes it all accessible to readers: inline live hyperlinks; live links to and from footnotes; automatic tables of contents (with live links!); tables; images for diagrams etc.; pleasant, readable styled text. The reStructuredText parser is available now, part of the Docutils project. Standalone reStructuredText documents and PEPs can be converted to HTML; other output format writers are being worked on and 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 Doc-SIG: It must be readable in source form by the casual observer.
It must be easy to type with any standard text editor. It must not need to contain information which can be deduced from parsing the module. It must contain sufficient information (structure) so it can be converted to any reasonable markup format. It must be possible to write a module’s entire documentation in docstrings, without feeling hampered by the markup language. reStructuredText meets and exceeds all of these goals, and sets its own goals as well, even more stringent.
See Docstring-Significant Features below. The goals of this PEP are as follows: 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. 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. To solicit and address any related concerns raised by the Python community. To encourage community support. As long as multiple competing markups are out there, the development community remains fractured. Once a standard exists, people will start to use it, and momentum will inevitably gather. To consolidate efforts from related auto-documentation projects.
It is hoped that interested developers will join forces and work on a joint/merged/common implementation. 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. With regard to PEPs, one or both of the following strategies may be applied: 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. 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). Strategy (b) is recommended, and its implementation is complete. 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 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, implicit markup has been sought, for the following reasons (among others): 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. Programmers want to add structure to their docstrings, without sacrificing raw docstring readability.
Unadorned plaintext cannot be transformed (“up-translated”) into useful structured formats. Explicit markup (like XML or TeX) is widely considered unreadable by the uninitiated. Implicit markup is aesthetically compatible with the clean and minimalist Python syntax. Many altern
The rest of this page is on the live site.