/Doc/documenting/style.rst

 1.. highlightlang:: rest
 2
 3Style Guide
 4===========
 5
 6The Python documentation should follow the `Apple Publications Style Guide`_
 7wherever possible. This particular style guide was selected mostly because it
 8seems reasonable and is easy to get online.
 9
10Topics which are not covered in the Apple's style guide will be discussed in
11this document.
12
13All reST files use an indentation of 3 spaces.  The maximum line length is 80
14characters for normal text, but tables, deeply indented code samples and long
15links may extend beyond that.
16
17Make generous use of blank lines where applicable; they help grouping things
18together.
19
20A sentence-ending period may be followed by one or two spaces; while reST
21ignores the second space, it is customarily put in by some users, for example
22to aid Emacs' auto-fill mode.
23
24Footnotes are generally discouraged, though they may be used when they are the
25best way to present specific information. When a footnote reference is added at
26the end of the sentence, it should follow the sentence-ending punctuation. The
27reST markup should appear something like this::
28
29    This sentence has a footnote reference. [#]_ This is the next sentence.
30
31Footnotes should be gathered at the end of a file, or if the file is very long,
32at the end of a section. The docutils will automatically create backlinks to
33the footnote reference.
34
35Footnotes may appear in the middle of sentences where appropriate.
36
37Many special names are used in the Python documentation, including the names of
38operating systems, programming languages, standards bodies, and the like. Most
39of these entities are not assigned any special markup, but the preferred
40spellings are given here to aid authors in maintaining the consistency of
41presentation in the Python documentation.
42
43Other terms and words deserve special mention as well; these conventions should
44be used to ensure consistency throughout the documentation:
45
46CPU
47    For "central processing unit." Many style guides say this should be spelled
48    out on the first use (and if you must use it, do so!). For the Python
49    documentation, this abbreviation should be avoided since there's no
50    reasonable way to predict which occurrence will be the first seen by the
51    reader. It is better to use the word "processor" instead.
52
53POSIX
54    The name assigned to a particular group of standards. This is always
55    uppercase.
56
57Python
58    The name of our favorite programming language is always capitalized.
59
60Unicode
61    The name of a character set and matching encoding. This is always written
62    capitalized.
63
64Unix
65    The name of the operating system developed at AT&T Bell Labs in the early
66    1970s.
67
68
69.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2008.pdf
70