2
Title: reStructuredText Docstring Format
3
Version: $Revision: 1.21 $
4
Last-Modified: $Date: 2002/11/09 20:58:34 $
5
Author: David Goodger <goodger@users.sourceforge.net>
6
Discussions-To: <doc-sig@python.org>
9
Content-Type: text/x-rst
11
Post-History: 02-Apr-2002
18
When plaintext hasn't been expressive enough for inline documentation,
19
Python programmers have sought out a format for docstrings. This PEP
20
proposes that the `reStructuredText markup`_ be adopted as a standard
21
markup format for structured plaintext documentation in Python
22
docstrings, and for PEPs and ancillary documents as well.
23
reStructuredText is a rich and extensible yet easy-to-read,
24
what-you-see-is-what-you-get plaintext markup syntax.
26
Only the low-level syntax of docstrings is addressed here. This PEP
27
is not concerned with docstring semantics or processing at all (see
28
PEP 256 for a "Road Map to the Docstring PEPs"). Nor is it an attempt
29
to deprecate pure plaintext docstrings, which are always going to be
30
legitimate. The reStructuredText markup is an alternative for those
31
who want more expressive docstrings.
37
Programmers are by nature a lazy breed. We reuse code with functions,
38
classes, modules, and subsystems. Through its docstring syntax,
39
Python allows us to document our code from within. The "holy grail"
40
of the Python Documentation Special Interest Group (Doc-SIG_) has been
41
a markup syntax and toolset to allow auto-documentation, where the
42
docstrings of Python systems can be extracted in context and processed
43
into useful, high-quality documentation for multiple purposes.
45
Document markup languages have three groups of customers: the authors
46
who write the documents, the software systems that process the data,
47
and the readers, who are the final consumers and the most important
48
group. Most markups are designed for the authors and software
49
systems; readers are only meant to see the processed form, either on
50
paper or via browser software. ReStructuredText is different: it is
51
intended to be easily readable in source form, without prior knowledge
52
of the markup. ReStructuredText is entirely readable in plaintext
53
format, and many of the markup forms match common usage (e.g.,
54
``*emphasis*``), so it reads quite naturally. Yet it is rich enough
55
to produce complex documents, and extensible so that there are few
56
limits. Of course, to write reStructuredText documents some prior
57
knowledge is required.
59
The markup offers functionality and expressivity, while maintaining
60
easy readability in the source text. The processed form (HTML etc.)
61
makes it all accessible to readers: inline live hyperlinks; live links
62
to and from footnotes; automatic tables of contents (with live
63
links!); tables; images for diagrams etc.; pleasant, readable styled
66
The reStructuredText parser is available now, part of the Docutils_
67
project. Standalone reStructuredText documents and PEPs can be
68
converted to HTML; other output format writers are being worked on and
69
will become available over time. Work is progressing on a Python
70
source "Reader" which will implement auto-documentation from
71
docstrings. Authors of existing auto-documentation tools are
72
encouraged to integrate the reStructuredText parser into their
73
projects, or better yet, to join forces to produce a world-class
74
toolset for the Python standard library.
76
Tools will become available in the near future, which will allow
77
programmers to generate HTML for online help, XML for multiple
78
purposes, and eventually PDF, DocBook, and LaTeX for printed
79
documentation, essentially "for free" from the existing docstrings.
80
The adoption of a standard will, at the very least, benefit docstring
81
processing tools by preventing further "reinventing the wheel".
83
Eventually PyDoc, the one existing standard auto-documentation tool,
84
could have reStructuredText support added. In the interim it will
85
have no problem with reStructuredText markup, since it treats all
86
docstrings as preformatted plaintext.
92
These are the generally accepted goals for a docstring format, as
93
discussed in the Doc-SIG:
95
1. It must be readable in source form by the casual observer.
97
2. It must be easy to type with any standard text editor.
99
3. It must not need to contain information which can be deduced from
102
4. It must contain sufficient information (structure) so it can be
103
converted to any reasonable markup format.
105
5. It must be possible to write a module's entire documentation in
106
docstrings, without feeling hampered by the markup language.
108
reStructuredText meets and exceeds all of these goals, and sets its
109
own goals as well, even more stringent. See `Docstring-Significant
112
The goals of this PEP are as follows:
114
1. To establish reStructuredText as a standard structured plaintext
115
format for docstrings (inline documentation of Python modules and
116
packages), PEPs, README-type files and other standalone documents.
117
"Accepted" status will be sought through Python community consensus
118
and eventual BDFL pronouncement.
120
Please note that reStructuredText is being proposed as *a*
121
standard, not *the only* standard. Its use will be entirely
122
optional. Those who don't want to use it need not.
124
2. To solicit and address any related concerns raised by the Python
127
3. To encourage community support. As long as multiple competing
128
markups are out there, the development community remains fractured.
129
Once a standard exists, people will start to use it, and momentum
130
will inevitably gather.
132
4. To consolidate efforts from related auto-documentation projects.
133
It is hoped that interested developers will join forces and work on
134
a joint/merged/common implementation.
136
Once reStructuredText is a Python standard, effort can be focused on
137
tools instead of arguing for a standard. Python needs a standard set
138
of documentation tools.
140
With regard to PEPs, one or both of the following strategies may be
143
a) Keep the existing PEP section structure constructs (one-line
144
section headers, indented body text). Subsections can either be
145
forbidden, or supported with reStructuredText-style underlined
146
headers in the indented body text.
148
b) Replace the PEP section structure constructs with the
149
reStructuredText syntax. Section headers will require underlines,
150
subsections will be supported out of the box, and body text need
151
not be indented (except for block quotes).
153
Strategy (b) is recommended, and its implementation is complete.
155
Support for RFC 2822 headers has been added to the reStructuredText
156
parser for PEPs (unambiguous given a specific context: the first
157
contiguous block of the document). It may be desired to concretely
158
specify what over/underline styles are allowed for PEP section
159
headers, for uniformity.
165
The lack of a standard syntax for docstrings has hampered the
166
development of standard tools for extracting and converting docstrings
167
into documentation in standard formats (e.g., HTML, DocBook, TeX).
168
There have been a number of proposed markup formats and variations,
169
and many tools tied to these proposals, but without a standard
170
docstring format they have failed to gain a strong following and/or
171
floundered half-finished.
173
Throughout the existence of the Doc-SIG, consensus on a single
174
standard docstring format has never been reached. A lightweight,
175
implicit markup has been sought, for the following reasons (among
178
1. Docstrings written within Python code are available from within the
179
interactive interpreter, and can be "print"ed. Thus the use of
180
plaintext for easy readability.
182
2. Programmers want to add structure to their docstrings, without
183
sacrificing raw docstring readability. Unadorned plaintext cannot
184
be transformed ("up-translated") into useful structured formats.
186
3. Explicit markup (like XML or TeX) is widely considered unreadable
189
4. Implicit markup is aesthetically compatible with the clean and
190
minimalist Python syntax.
192
Many alternative markups for docstrings have been proposed on the
193
Doc-SIG over the years; a representative sample is listed below. Each
194
is briefly analyzed in terms of the goals stated above. Please note
195
that this is *not* intended to be an exclusive list of all existing
196
markup systems; there are many other markups (Texinfo, Doxygen, TIM,
197
YODL, AFT, ...) which are not mentioned.
199
- XML_, SGML_, DocBook_, HTML_, XHTML_
201
XML and SGML are explicit, well-formed meta-languages suitable for
202
all kinds of documentation. XML is a variant of SGML. They are
203
best used behind the scenes, because to untrained eyes they are
204
verbose, difficult to type, and too cluttered to read comfortably as
205
source. DocBook, HTML, and XHTML are all applications of SGML
206
and/or XML, and all share the same basic syntax and the same
211
TeX is similar to XML/SGML in that it's explicit, but not very easy
212
to write, and not easy for the uninitiated to read.
216
Most Perl modules are documented in a format called POD (Plain Old
217
Documentation). This is an easy-to-type, very low level format with
218
strong integration with the Perl parser. Many tools exist to turn
219
POD documentation into other formats: info, HTML and man pages,
220
among others. However, the POD syntax takes after Perl itself in
221
terms of readability.
225
Special comments before Java classes and functions serve to document
226
the code. A program to extract these, and turn them into HTML
227
documentation is called javadoc, and is part of the standard Java
228
distribution. However, JavaDoc has a very intimate relationship
229
with HTML, using HTML tags for most markup. Thus it shares the
230
readability problems of HTML.
232
- Setext_, StructuredText_
234
Early on, variants of Setext (Structure Enhanced Text), including
235
Zope Corp's StructuredText, were proposed for Python docstring
236
formatting. Hereafter these variants will collectively be called
237
"STexts". STexts have the advantage of being easy to read without
238
special knowledge, and relatively easy to write.
240
Although used by some (including in most existing Python
241
auto-documentation tools), until now STexts have failed to become
244
- STexts have been incomplete. Lacking "essential" constructs that
245
people want to use in their docstrings, STexts are rendered less
246
than ideal. Note that these "essential" constructs are not
247
universal; everyone has their own requirements.
249
- STexts have been sometimes surprising. Bits of text are
250
unexpectedly interpreted as being marked up, leading to user
253
- SText implementations have been buggy.
255
- Most STexts have have had no formal specification except for the
256
implementation itself. A buggy implementation meant a buggy spec,
259
- There has been no mechanism to get around the SText markup rules
260
when a markup character is used in a non-markup context. In other
261
words, no way to escape markup.
263
Proponents of implicit STexts have vigorously opposed proposals for
264
explicit markup (XML, HTML, TeX, POD, etc.), and the debates have
265
continued off and on since 1996 or earlier.
267
reStructuredText is a complete revision and reinterpretation of the
268
SText idea, addressing all of the problems listed above.
274
The specification and user documentaton for reStructuredText is
275
quite extensive. Rather than repeating or summarizing it all
276
here, links to the originals are provided.
278
Please first take a look at `A ReStructuredText Primer`_, a short and
279
gentle introduction. The `Quick reStructuredText`_ user reference
280
quickly summarizes all of the markup constructs. For complete and
281
extensive details, please refer to the following documents:
283
- `An Introduction to reStructuredText`_
285
- `reStructuredText Markup Specification`_
287
- `reStructuredText Directives`_
289
In addition, `Problems With StructuredText`_ explains many markup
290
decisions made with regards to StructuredText, and `A Record of
291
reStructuredText Syntax Alternatives`_ records markup decisions made
295
Docstring-Significant Features
296
==============================
298
- A markup escaping mechanism.
300
Backslashes (``\``) are used to escape markup characters when needed
301
for non-markup purposes. However, the inline markup recognition
302
rules have been constructed in order to minimize the need for
303
backslash-escapes. For example, although asterisks are used for
304
*emphasis*, in non-markup contexts such as "*" or "(*)" or "x * y",
305
the asterisks are not interpreted as markup and are left unchanged.
306
For many non-markup uses of backslashes (e.g., describing regular
307
expressions), inline literals or literal blocks are applicable; see
310
- Markup to include Python source code and Python interactive
311
sessions: inline literals, literal blocks, and doctest blocks.
313
Inline literals use ``double-backquotes`` to indicate program I/O or
314
code snippets. No markup interpretation (including backslash-escape
315
[``\``] interpretation) is done within inline literals.
317
Literal blocks (block-level literal text, such as code excerpts or
318
ASCII graphics) are indented, and indicated with a double-colon
319
("::") at the end of the preceding paragraph (right here -->)::
322
text = 'is left as-is'
323
spaces_and_linebreaks = 'are preserved'
324
markup_processing = None
326
Doctest blocks begin with ">>> " and end with a blank line. Neither
327
indentation nor literal block double-colons are required. For
330
Here's a doctest block:
332
>>> print 'Python-specific usage examples; begun with ">>>"'
333
Python-specific usage examples; begun with ">>>"
334
>>> print '(cut and pasted from interactive sessions)'
335
(cut and pasted from interactive sessions)
337
- Markup that isolates a Python identifier: interpreted text.
339
Text enclosed in single backquotes is recognized as "interpreted
340
text", whose interpretation is application-dependent. In the
341
context of a Python docstring, the default interpretation of
342
interpreted text is as Python identifiers. The text will be marked
343
up with a hyperlink connected to the documentation for the
344
identifier given. Lookup rules are the same as in Python itself:
345
LGB namespace lookups (local, global, builtin). The "role" of the
346
interpreted text (identifying a class, module, function, etc.) is
347
determined implicitly from the namespace lookup. For example::
349
class Keeper(Storer):
352
Keep data fresher longer.
354
Extend `Storer`. Class attribute `instances` keeps track
355
of the number of `Keeper` objects instantiated.
359
"""How many `Keeper` objects are there?"""
363
Extend `Storer.__init__()` to keep track of
364
instances. Keep count in `self.instances` and data
367
Storer.__init__(self)
371
"""Store data in a list, most recent last."""
373
def storedata(self, data):
375
Extend `Storer.storedata()`; append new `data` to a
376
list (in `self.data`).
380
Each piece of interpreted text is looked up according to the local
381
namespace of the block containing its docstring.
383
- Markup that isolates a Python identifier and specifies its type:
384
interpreted text with roles.
386
Although the Python source context reader is designed not to require
387
explicit roles, they may be used. To classify identifiers
388
explicitly, the role is given along with the identifier in either
389
prefix or suffix form::
391
Use :method:`Keeper.storedata` to store the object's data in
392
`Keeper.data`:instance_attribute:.
394
The syntax chosen for roles is verbose, but necessarily so (if
395
anyone has a better alternative, please post it to the Doc-SIG_).
396
The intention of the markup is that there should be little need to
397
use explicit roles; their use is to be kept to an absolute minimum.
399
- Markup for "tagged lists" or "label lists": field lists.
401
Field lists represent a mapping from field name to field body.
402
These are mostly used for extension syntax, such as "bibliographic
403
field lists" (representing document metadata such as author, date,
404
and version) and extension attributes for directives (see below).
405
They may be used to implement methodologies (docstring semantics),
406
such as identifying parameters, exceptions raised, etc.; such usage
407
is beyond the scope of this PEP.
409
A modified RFC 2822 syntax is used, with a colon *before* as well as
410
*after* the field name. Field bodies are more versatile as well;
411
they may contain multiple field bodies (even nested field lists).
421
Standard RFC 2822 header syntax cannot be used for this construct
422
because it is ambiguous. A word followed by a colon at the
423
beginning of a line is common in written text.
425
- Markup extensibility: directives and substitutions.
427
Directives are used as an extension mechanism for reStructuredText,
428
a way of adding support for new block-level constructs without
429
adding new syntax. Directives for images, admonitions (note,
430
caution, etc.), and tables of contents generation (among others)
431
have been implemented. For example, here's how to place an image::
433
.. image:: mylogo.png
435
Substitution definitions allow the power and flexibility of
436
block-level directives to be shared by inline text. For example::
438
The |biohazard| symbol must be used on containers used to
439
dispose of medical waste.
441
.. |biohazard| image:: biohazard.png
443
- Section structure markup.
445
Section headers in reStructuredText use adornment via underlines
446
(and possibly overlines) rather than indentation. For example::
448
This is a Section Title
449
=======================
451
This is a Subsection Title
452
--------------------------
454
This paragraph is in the subsection.
456
This is Another Section Title
457
=============================
459
This paragraph is in the second section.
465
1. Is reStructuredText rich enough?
467
Yes, it is for most people. If it lacks some construct that is
468
required for a specific application, it can be added via the
469
directive mechanism. If a useful and common construct has been
470
overlooked and a suitably readable syntax can be found, it can be
471
added to the specification and parser.
473
2. Is reStructuredText *too* rich?
475
For specific applications or individuals, perhaps. In general, no.
477
Since the very beginning, whenever a docstring markup syntax has
478
been proposed on the Doc-SIG_, someone has complained about the
479
lack of support for some construct or other. The reply was often
480
something like, "These are docstrings we're talking about, and
481
docstrings shouldn't have complex markup." The problem is that a
482
construct that seems superfluous to one person may be absolutely
483
essential to another.
485
reStructuredText takes the opposite approach: it provides a rich
486
set of implicit markup constructs (plus a generic extension
487
mechanism for explicit markup), allowing for all kinds of
488
documents. If the set of constructs is too rich for a particular
489
application, the unused constructs can either be removed from the
490
parser (via application-specific overrides) or simply omitted by
493
3. Why not use indentation for section structure, like StructuredText
494
does? Isn't it more "Pythonic"?
496
Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post:
498
I still think that using indentation to indicate sectioning is
499
wrong. If you look at how real books and other print
500
publications are laid out, you'll notice that indentation is
501
used frequently, but mostly at the intra-section level.
502
Indentation can be used to offset lists, tables, quotations,
503
examples, and the like. (The argument that docstrings are
504
different because they are input for a text formatter is wrong:
505
the whole point is that they are also readable without
508
I reject the argument that using indentation is Pythonic: text
509
is not code, and different traditions and conventions hold.
510
People have been presenting text for readability for over 30
511
centuries. Let's not innovate needlessly.
513
See `Section Structure via Indentation`__ in `Problems With
514
StructuredText`_ for further elaboration.
516
__ http://docutils.sourceforge.net/spec/rst/problems.html
517
#section-structure-via-indentation
519
4. Why use reStructuredText for PEPs? What's wrong with the existing
522
The existing standard for PEPs is very limited in terms of general
523
expressibility, and referencing is especially lacking for such a
524
reference-rich document type. PEPs are currently converted into
525
HTML, but the results (mostly monospaced text) are less than
526
attractive, and most of the value-added potential of HTML
527
(especially inline hyperlinks) is untapped.
529
Making reStructuredText a standard markup for PEPs will enable much
530
richer expression, including support for section structure, inline
531
markup, graphics, and tables. In several PEPs there are ASCII
532
graphics diagrams, which are all that plaintext documents can
533
support. Since PEPs are made available in HTML form, the ability
534
to include proper diagrams would be immediately useful.
536
Current PEP practices allow for reference markers in the form "[1]"
537
in the text, and the footnotes/references themselves are listed in
538
a section toward the end of the document. There is currently no
539
hyperlinking between the reference marker and the
540
footnote/reference itself (it would be possible to add this to
541
pep2html.py, but the "markup" as it stands is ambiguous and
542
mistakes would be inevitable). A PEP with many references (such as
543
this one ;-) requires a lot of flipping back and forth. When
544
revising a PEP, often new references are added or unused references
545
deleted. It is painful to renumber the references, since it has to
546
be done in two places and can have a cascading effect (insert a
547
single new reference 1, and every other reference has to be
548
renumbered; always adding new references to the end is suboptimal).
549
It is easy for references to go out of sync.
551
PEPs use references for two purposes: simple URL references and
552
footnotes. reStructuredText differentiates between the two. A PEP
553
might contain references like this::
557
This PEP proposes adding frungible doodads [1] to the core.
558
It extends PEP 9876 [2] via the BCA [3] mechanism.
562
References and Footnotes
564
[1] http://www.example.org/
566
[2] PEP 9876, Let's Hope We Never Get Here
567
http://www.python.org/peps/pep-9876.html
569
[3] "Bogus Complexity Addition"
571
Reference 1 is a simple URL reference. Reference 2 is a footnote
572
containing text and a URL. Reference 3 is a footnote containing
573
text only. Rewritten using reStructuredText, this PEP could look
579
This PEP proposes adding `frungible doodads`_ to the core. It
580
extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.
584
References & Footnotes
585
======================
587
.. _frungible doodads: http://www.example.org/
589
.. [#pep9876] PEP 9876, Let's Hope We Never Get Here
591
.. [#] "Bogus Complexity Addition"
593
URLs and footnotes can be defined close to their references if
594
desired, making them easier to read in the source text, and making
595
the PEPs easier to revise. The "References and Footnotes" section
596
can be auto-generated with a document tree transform. Footnotes
597
from throughout the PEP would be gathered and displayed under a
598
standard header. If URL references should likewise be written out
599
explicitly (in citation form), another tree transform could be
602
URL references can be named ("frungible doodads"), and can be
603
referenced from multiple places in the document without additional
604
definitions. When converted to HTML, references will be replaced
605
with inline hyperlinks (HTML <a> tags). The two footnotes are
606
automatically numbered, so they will always stay in sync. The
607
first footnote also contains an internal reference name, "pep9876",
608
so it's easier to see the connection between reference and footnote
609
in the source text. Named footnotes can be referenced multiple
610
times, maintaining consistent numbering.
612
The "#pep9876" footnote could also be written in the form of a
615
It extends PEP 9876 [PEP9876]_ ...
617
.. [PEP9876] PEP 9876, Let's Hope We Never Get Here
619
Footnotes are numbered, whereas citations use text for their
622
5. Wouldn't it be better to keep the docstring and PEP proposals
625
The PEP markup proposal may be removed if it is deemed that there
626
is no need for PEP markup, or it could be made into a separate PEP.
627
If accepted, PEP 1, PEP Purpose and Guidelines [#PEP-1]_, and PEP
628
9, Sample PEP Template [#PEP-9]_ will be updated.
630
It seems natural to adopt a single consistent markup standard for
631
all uses of structured plaintext in Python, and to propose it all
634
6. The existing pep2html.py script converts the existing PEP format to
635
HTML. How will the new-format PEPs be converted to HTML?
637
A new version of pep2html.py with integrated reStructuredText
638
parsing has been completed. The Docutils project supports PEPs
639
with a "PEP Reader" component, including all functionality
640
currently in pep2html.py (auto-recognition of PEP & RFC references,
641
email masking, etc.).
643
7. Who's going to convert the existing PEPs to reStructuredText?
645
PEP authors or volunteers may convert existing PEPs if they like,
646
but there is no requirement to do so. The reStructuredText-based
647
PEPs will coexist with the old PEP standard. The pep2html.py
648
mentioned in answer 6 processes both old and new standards.
650
8. Why use reStructuredText for README and other ancillary files?
652
The reasoning given for PEPs in answer 4 above also applies to
653
README and other ancillary files. By adopting a standard markup,
654
these files can be converted to attractive cross-referenced HTML
655
and put up on python.org. Developers of other projects can also
656
take advantage of this facility for their own documentation.
658
9. Won't the superficial similarity to existing markup conventions
659
cause problems, and result in people writing invalid markup (and
660
not noticing, because the plaintext looks natural)? How forgiving
661
is reStructuredText of "not quite right" markup?
663
There will be some mis-steps, as there would be when moving from
664
one programming language to another. As with any language,
665
proficiency grows with experience. Luckily, reStructuredText is a
666
very little language indeed.
668
As with any syntax, there is the possibility of syntax errors. It
669
is expected that a user will run the processing system over their
670
input and check the output for correctness.
672
In a strict sense, the reStructuredText parser is very unforgiving
673
(as it should be; "In the face of ambiguity, refuse the temptation
674
to guess" [#Zen]_ applies to parsing markup as well as computer
675
languages). Here's design goal 3 from `An Introduction to
678
Unambiguous. The rules for markup must not be open for
679
interpretation. For any given input, there should be one and
680
only one possible output (including error output).
682
While unforgiving, at the same time the parser does try to be
683
helpful by producing useful diagnostic output ("system messages").
684
The parser reports problems, indicating their level of severity
685
(from least to most: debug, info, warning, error, severe). The
686
user or the client software can decide on reporting thresholds;
687
they can ignore low-level problems or cause high-level problems to
688
bring processing to an immediate halt. Problems are reported
689
during the parse as well as included in the output, often with
690
two-way links between the source of the problem and the system
691
message explaining it.
693
10. Will the docstrings in the Python standard library modules be
694
converted to reStructuredText?
696
No. Python's library reference documentation is maintained
697
separately from the source. Docstrings in the Python standard
698
library should not try to duplicate the library reference
699
documentation. The current policy for docstrings in the Python
700
standard library is that they should be no more than concise
701
hints, simple and markup-free (although many *do* contain ad-hoc
704
11. I want to write all my strings in Unicode. Will anything
707
The parser fully supports Unicode. Docutils supports arbitrary
708
input and output encodings.
710
12. Why does the community need a new structured text design?
712
The existing structured text designs are deficient, for the
713
reasons given in "Rationale" above. reStructuredText aims to be a
714
complete markup syntax, within the limitations of the "readable
717
13. What is wrong with existing documentation methodologies?
719
What existing methodologies? For Python docstrings, there is
720
**no** official standard markup format, let alone a documentation
721
methodology akin to JavaDoc. The question of methodology is at a
722
much higher level than syntax (which this PEP addresses). It is
723
potentially much more controversial and difficult to resolve, and
724
is intentionally left out of this discussion.
727
References & Footnotes
728
======================
730
.. [#PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton
731
(http://www.python.org/peps/pep-0001.html)
733
.. [#PEP-9] PEP 9, Sample PEP Template, Warsaw
734
(http://www.python.org/peps/pep-0009.html)
736
.. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just
737
"``import this``" in Python)
739
__ http://www.python.org/doc/Humor.html#zen
741
.. [#PEP-216] PEP 216, Docstring Format, Zadka
742
(http://www.python.org/peps/pep-0216.html)
744
.. _reStructuredText markup: http://docutils.sourceforge.net/spec/rst.html
746
.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
748
.. _XML: http://www.w3.org/XML/
750
.. _SGML: http://www.oasis-open.org/cover/general.html
752
.. _DocBook: http://docbook.org/tdg/en/html/docbook.html
754
.. _HTML: http://www.w3.org/MarkUp/
756
.. _XHTML: http://www.w3.org/MarkUp/#xhtml1
758
.. _TeX: http://www.tug.org/interest.html
760
.. _Perl POD: http://www.perldoc.com/perl5.6/pod/perlpod.html
762
.. _JavaDoc: http://java.sun.com/j2se/javadoc/
764
.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
767
http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage
769
.. _A ReStructuredText Primer:
770
http://docutils.sourceforge.net/docs/rst/quickstart.html
772
.. _Quick reStructuredText:
773
http://docutils.sourceforge.net/docs/rst/quickref.html
775
.. _An Introduction to reStructuredText:
776
http://docutils.sourceforge.net/spec/rst/introduction.html
778
.. _reStructuredText Markup Specification:
779
http://docutils.sourceforge.net/spec/rst/reStructuredText.html
781
.. _reStructuredText Directives:
782
http://docutils.sourceforge.net/spec/rst/directives.html
784
.. _Problems with StructuredText:
785
http://docutils.sourceforge.net/spec/rst/problems.html
787
.. _A Record of reStructuredText Syntax Alternatives:
788
http://docutils.sourceforge.net/spec/rst/alternatives.html
790
.. _Docutils: http://docutils.sourceforge.net/
796
This document has been placed in the public domain.
802
Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by
805
Special thanks to all members past & present of the Python Doc-SIG_.
812
indent-tabs-mode: nil
813
sentence-end-double-space: t
added
removed
spec/pep-0287.txt
