Update docs conventions based on recent experience

docs/html/development/conventions.rst

@@ -10,9 +10,9 @@ and past conventions are rendered obsolete.
 
 .. note::
 
-    Currently, these conventions are not enforced automatically, and
-    need to be verified manually during code review. We are interested
-    in linters that can help us enforce these conventions automatically.
+   Currently, these conventions are not enforced automatically, and
+   need to be verified manually during code review. We are interested
+   in linters that can help us enforce these conventions automatically.
 
 
 Files
@@ -45,27 +45,42 @@ code blocks).
 Indentation
 -----------
 
-We use 4 spaces for indentation.
+We use 3 spaces for indentation.
 
 ::
 
-    .. note::
+   .. note::
 
-        Directive blocks
+      Directive blocks
 
-    ::
+   ::
 
-        Code block.
+      Code block.
 
-Bullet lists are the only exception to the 4 spaces rule, using 2 spaces
+Bullet lists are the only exception to the 3 spaces rule, using 2 spaces
 when wrapping lines.
 
 ::
 
-    - This is a bullet list.
-    - This is a lot of text in a single bullet which would require wrapping
-      across multiple lines to fit in the line length limits.
+   - This is a bullet list.
+   - This is a lot of text in a single bullet which would require wrapping
+     across multiple lines to fit in the line length limits.
 
+Note that nested lists would use 3 spaces for indentation, and require
+blank lines on either side (that's the ReST syntax).
+
+::
+
+   - This is a bullet list.
+   - There is a nested list associated with this list item.
+
+      - This is a nested bullet list.
+      - With multiple bullets even.
+      - And some of the bullets have really long sentences that would
+        require wrapping across multiple lines.
+
+   - This is a lot of text in a single bullet which would require wrapping
+     across multiple lines to fit in the line length limits.
 
 Headings
 ========
@@ -86,42 +101,47 @@ it.
 
 ::
 
-    =========
-    Heading 1
-    =========
+   =========
+   Heading 1
+   =========
 
-    Lorem ipsum dolor sit amet consectetur adipisicing elit.
+   Lorem ipsum dolor sit amet consectetur adipisicing elit.
 
 
-    Heading 2
-    =========
+   Heading 2
+   =========
 
-    Lorem ipsum dolor sit amet consectetur adipisicing elit.
+   Lorem ipsum dolor sit amet consectetur adipisicing elit.
 
-    Heading 3
-    ---------
+   Heading 3
+   ---------
 
-    Lorem ipsum dolor sit amet consectetur adipisicing elit.
+   Lorem ipsum dolor sit amet consectetur adipisicing elit.
 
-    Heading 4
-    ^^^^^^^^^
+   Heading 4
+   ^^^^^^^^^
 
-    Lorem ipsum dolor sit amet consectetur adipisicing elit.
+   Lorem ipsum dolor sit amet consectetur adipisicing elit.
 
-    Heading 5
-    '''''''''
+   Heading 5
+   '''''''''
 
-    Lorem ipsum dolor sit amet consectetur adipisicing elit.
+   Lorem ipsum dolor sit amet consectetur adipisicing elit.
 
-    Heading 6
-    *********
+   Heading 6
+   *********
 
-    Lorem ipsum dolor sit amet consectetur adipisicing elit.
+   Lorem ipsum dolor sit amet consectetur adipisicing elit.
 
 
 Writing
 =======
 
+.. note::
+
+   We're still discussing *how* pip should be capitalized in prose. The
+   current statement here is tentative.
+
 pip is a proper noun, and spelt all lowercase. Do not capitalize pip as
 "Pip" at the start of a sentence.