[docs] Use of title-case in section titles

Alexander Belopolsky alexander.belopolsky at gmail.com
Wed Nov 10 16:27:16 CET 2010


Apple style guide recommends that section titles be written in
title-case (a set of confusing rules where most words are
capitalized).  However, with few exceptions, per module sections have
titles with only the first word in capitals:

6. String Services
6.1. string — Common string operations
6.2. re — Regular expression operations
..
6.7. unicodedata — Unicode Database
6.8. stringprep — Internet String Preparation

Third level subsections are mostly capitalizing the first word as
well.   I personally prefer to use sentence case in section titles.
Note that  "string — Common string operations" is neither sentence nor
title case: it title-case it would be "string — Common String
Operations" and in sentence-case, it would be ""string — common string
operations" because the first word of the sentence is "string", not
"common".

Since most of the existing documentation does not follow Apple style
guide in this respect, I think we should document an appropriate
recommendation in Python documentation style guide and use it more
consistently.


More information about the docs mailing list