cpython/Doc/documenting/style.rst

71 lines
2.7 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
.. 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 not covered in the Apple's style guide will be discussed in
this document.
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.
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.
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.
Unicode
The name of a character set and matching encoding. This is always written
capitalized.
Unix
The name of the operating system developed at AT&T Bell Labs in the early
1970s.
Merged revisions 67154,67157-67159,67162-67163,67166,67175-67176,67189,67224-67225,67243 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67154 | hirokazu.yamamoto | 2008-11-08 04:46:17 +0100 (Sat, 08 Nov 2008) | 1 line Issue #4071: ntpath.abspath returned an empty string for long unicode path. ........ r67157 | georg.brandl | 2008-11-08 12:47:44 +0100 (Sat, 08 Nov 2008) | 2 lines Don't use "HOWTO" as the title for all howto .tex files. ........ r67158 | georg.brandl | 2008-11-08 12:48:20 +0100 (Sat, 08 Nov 2008) | 2 lines Update "Documenting" a bit. Concentrate on Python-specifics. ........ r67159 | georg.brandl | 2008-11-08 13:52:25 +0100 (Sat, 08 Nov 2008) | 2 lines Fix warning. ........ r67162 | benjamin.peterson | 2008-11-08 17:55:33 +0100 (Sat, 08 Nov 2008) | 1 line a few compile() and ast doc improvements ........ r67163 | benjamin.peterson | 2008-11-08 18:04:18 +0100 (Sat, 08 Nov 2008) | 1 line move context clue to versionchanged tag ........ r67166 | benjamin.peterson | 2008-11-08 18:07:06 +0100 (Sat, 08 Nov 2008) | 1 line clarify what was added ........ r67175 | benjamin.peterson | 2008-11-09 02:44:32 +0100 (Sun, 09 Nov 2008) | 1 line update link ........ r67176 | benjamin.peterson | 2008-11-09 02:52:32 +0100 (Sun, 09 Nov 2008) | 1 line fix comment ........ r67189 | benjamin.peterson | 2008-11-11 22:56:06 +0100 (Tue, 11 Nov 2008) | 1 line use correct name ........ r67224 | georg.brandl | 2008-11-15 09:10:04 +0100 (Sat, 15 Nov 2008) | 2 lines #4324: fix getlocale() argument. ........ r67225 | brett.cannon | 2008-11-15 23:33:25 +0100 (Sat, 15 Nov 2008) | 1 line Clarify the docs for the 'strict' argument to httplib.HTTPConnection. ........ r67243 | benjamin.peterson | 2008-11-17 22:39:05 +0100 (Mon, 17 Nov 2008) | 1 line a few fixes on the download page ........
2008-12-05 04:35:09 -04:00
.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2008.pdf
2007-08-15 11:28:01 -03:00