| |
| Style Guide |
| =========== |
| |
| The Python documentation should follow the `Apple Publications Style Guide`_ |
| wherever possible. This particular style guide was selected mostly because it |
| seems reasonable and is easy to get online. |
| |
n | .. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf |
n | Topics which are not covered in the Apple's style guide will be discussed in |
| this document. |
| |
n | Topics which are not covered in the Apple's style guide will be discussed in |
n | All reST files use an indentation of 3 spaces. The maximum line length is 80 |
| this document if necessary. |
| characters for normal text, but tables, deeply indented code samples and long |
| links may extend beyond that. |
| |
| Make generous use of blank lines where applicable; they help grouping things |
| together. |
| |
| A sentence-ending period may be followed by one or two spaces; while reST |
| ignores the second space, it is customarily put in by some users, for example |
| to aid Emacs' auto-fill mode. |
| |
| Footnotes are generally discouraged, though they may be used when they are the |
| best way to present specific information. When a footnote reference is added at |
| the end of the sentence, it should follow the sentence-ending punctuation. The |
| reST markup should appear something like this:: |
| |
| This sentence has a footnote reference. [#]_ This is the next sentence. |
| |
| Footnotes should be gathered at the end of a file, or if the file is very long, |
n | at the end of a section. The docutils will automatically create backlinks to the |
n | at the end of a section. The docutils will automatically create backlinks to |
| footnote reference. |
| the footnote reference. |
| |
| Footnotes may appear in the middle of sentences where appropriate. |
| |
| Many special names are used in the Python documentation, including the names of |
| operating systems, programming languages, standards bodies, and the like. Most |
| of these entities are not assigned any special markup, but the preferred |
| spellings are given here to aid authors in maintaining the consistency of |
| presentation in the Python documentation. |