From 2954362448347a6a3efd55222a50ece8e2fae6a0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 21:53:39 -0800 Subject: update headings --- docs/style-guide.rst | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 49c9d5950..4a17e1d2b 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -67,6 +67,7 @@ Each section, or a subdirectory of reST files, such as a tutorial, must contain chapter2 chapter3 + .. _style-guide-page-structure: Page structure @@ -104,10 +105,18 @@ Each page should contain in order the following. - Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on. +.. _style-guide-page-content: + +Page content +------------ + +Within a page, content should adhere to specific guidelines. + + .. _style-guide-line-lengths: Line lengths ------------- +^^^^^^^^^^^^ Narrative documentation is not code, and should therefore not adhere to PEP8 or other line length conventions. When a translator sees only part of a sentence or paragraph, it makes it more difficult to translate the concept. Line lengths make ``diff`` more difficult. Text editors can soft wrap lines for display to avoid horizontal scrolling. We admit, we boofed it by using arbitrary 79-character line lengths in our own documentation, but we have seen the error of our ways and wish to correct this going forward. @@ -115,7 +124,7 @@ Narrative documentation is not code, and should therefore not adhere to PEP8 or .. _style-guide-trailing-white-space: Trailing white spaces ---------------------- +^^^^^^^^^^^^^^^^^^^^^ - No trailing white spaces. - Always use a line feed or carriage return at the end of a file. @@ -124,7 +133,7 @@ Trailing white spaces .. _style-guide-indentation: Indentation ------------ +^^^^^^^^^^^ - Indent using four spaces. - Do not use tabs to indent. @@ -133,15 +142,37 @@ Indentation .. _style-guide-headings: Headings --------- +^^^^^^^^ + +Capitalize only the first letter in a heading (sentence-case), unless other words are proper nouns or acronyms, e.g., "Pyramid" or "HTML". + +For consistent heading characters throughout the documentation, follow the guidelines stated in the `Python Developer's Guide `_. Specifically: + +- =, for sections +- -, for subsections +- ^, for subsubsections +- ", for paragraphs + +As individual files do not have so-called "parts" or "chapters", the headings would be underlined with characters as shown. + + .. code-block:: rst + + Heading Level 1 + =============== + + Heading Level 2 + --------------- -Capitalize only the first letter in a heading, unless other words are proper nouns or acronyms, e.g., "Pyramid" or "HTML". + Heading Level 3 + ^^^^^^^^^^^^^^^ + Heading Level 4 + ``````````````` .. _style-guide-paragraphs: Paragraphs ----------- +^^^^^^^^^^ A paragraph should be on one line. Paragraphs must be separated by two line feeds. @@ -149,7 +180,7 @@ A paragraph should be on one line. Paragraphs must be separated by two line feed .. _style-guide-grammar-spelling-preferences: Grammar, spelling, and capitalization preferences -------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use any commercial or free professional style guide in general. Use a spell- and grammar-checker. The following table lists the preferred grammar, spelling, and capitalization of words and phrases for frequently used items in the documentation. -- cgit v1.2.3