115 lines
4.2 KiB
ReStructuredText
115 lines
4.2 KiB
ReStructuredText
.. highlightlang:: rest
|
|
|
|
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.
|
|
|
|
Topics which are either not covered in Apple's style guide or treated
|
|
differently in Python documentation will be discussed in this
|
|
document.
|
|
|
|
Use of whitespace
|
|
-----------------
|
|
|
|
All reST files use an indentation of 3 spaces; no tabs are allowed. The
|
|
maximum line length is 80 characters for normal text, but tables, deeply
|
|
indented code samples and long links may extend beyond that. Code example
|
|
bodies should use normal Python 4-space indentation.
|
|
|
|
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
|
|
---------
|
|
|
|
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.
|
|
|
|
Capitalization
|
|
--------------
|
|
|
|
.. sidebar:: Sentence case
|
|
|
|
Sentence case is a set of capitalization rules used in English
|
|
sentences: the first word is always capitalized and other words are
|
|
only capitalized if there is a specific rule requiring it.
|
|
|
|
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.
|
|
|
|
.. note::
|
|
|
|
Sections that describe a library module often have titles in the
|
|
form of "modulename --- Short description of the module." In this
|
|
case, the description should be capitalized as a stand-alone
|
|
sentence.
|
|
|
|
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.
|
|
|
|
|
|
.. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf
|
|
|