Issue #10389: Documented rules for use of case in section titles.

Doc/documenting/style.rst

@@ -1,14 +1,18 @@
 .. highlightlang:: rest
 
-Style Guide
+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 Apple's style guide will be discussed in
+Topics which are either not covered in Apple's style guide or treated
-this document.
+differently in Python documentation will be discussed in this
+document.
+
+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
@@ -21,6 +25,9 @@ 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
@@ -34,6 +41,36 @@ 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
@@ -44,26 +81,32 @@ 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
+   For "central processing unit." Many style guides say this should be
-    out on the first use (and if you must use it, do so!). For the Python
+   spelled out on the first use (and if you must use it, do so!). For
-    documentation, this abbreviation should be avoided since there's no
+   the Python documentation, this abbreviation should be avoided since
-    reasonable way to predict which occurrence will be the first seen by the
+   there's no reasonable way to predict which occurrence will be the
-    reader. It is better to use the word "processor" instead.
+   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
+   The name assigned to a particular group of standards. This is always
-    uppercase.
+   uppercase.
 
 Python
-    The name of our favorite programming language is always capitalized.
+   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 set and matching encoding. This is always written
+   The name of a character coding system. This is always written
-    capitalized.
+   capitalized.
 
 Unix
-    The name of the operating system developed at AT&T Bell Labs in the early
+   The name of the operating system developed at AT&T Bell Labs in the early
-    1970s.
+   1970s.
 
 
 .. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf