2.1. Use of whitespace

All reST files use an indentation of 3 spaces. The maximum line length is 80 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.

2.2. Footnotes

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, at the end of a section. The docutils will automatically create backlinks to the footnote reference.

Footnotes may appear in the middle of sentences where appropriate.

2.3. Capitalization

Apple style guide recommends the use of title case in section titles. However, rules for which words should be capitalized in title case vary greaty between publications.

In Python documentation, use of sentence case in section titles is preferable, but consistency within a unit is more important than following this rule. If you add a section to the chapter where most sections are in title case you can either convert all titles to sentence case or use the dominant style in the new section title.

Sentences that start with a word for which specific rules require starting it with a lower case letter should be avoided in titles and elsewhere.

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.

Other terms and words deserve special mention as well; these conventions should be used to ensure consistency throughout the documentation:

CPU

For “central processing unit.” Many style guides say this should be spelled out on the first use (and if you must use it, do so!). For the Python documentation, this abbreviation should be avoided since there’s no reasonable way to predict which occurrence will be the first seen by the reader. It is better to use the word “processor” instead.

POSIX

The name assigned to a particular group of standards. This is always uppercase.

Python

The name of our favorite programming language is always capitalized.

reST

For “reStructuredText,” an easy to read, plaintext markup syntax used to produce Python documentation. When spelled out, it is always one word and both forms start with a lower case ‘r’.

Unicode

The name of a character coding system. This is always written capitalized.

Unix

The name of the operating system developed at AT&T Bell Labs in the early 1970s.