code_style: more formatting

docs/code_style.rst

@@ -1,26 +1,13 @@
 - Everything should comply with PEP8. Code should pass
   ``pep8 --max-line-length=100`` without any warnings.
-- NEVER tabs. 4 spaces to indent.
+
-- Max line width: 79 chars (with flexibility to overflow by a "few chars" if
+- **Indenting**:
-  the overflowing content is not semantically significant and avoids an
+
-  explosion of vertical whitespace).
+  - NEVER tabs. 4 spaces to indent.
-- Use camel case for class and type names
+
-- Use underscores for functions and variables.
+  - follow PEP8; either hanging indent or multiline-visual indent depending
-- Use double quotes.
+    on the size and shape of the arguments and what makes more sense to the
-- Use parentheses instead of '\\' for line continuation where ever possible
+    author. In other words, both this::
-  (which is pretty much everywhere)
-- There should be max a single new line between:
-    - statements
-    - functions in a class
-- There should be two new lines between:
-    - definitions in a module (e.g., between different classes)
-- There should be spaces where spaces should be and not where there shouldn't be:
-    - a single space after a comma
-    - a single space before and after for '=' when used as assignment
-    - no spaces before and after for '=' for default values and keyword arguments.
-- Indenting must follow PEP8; either hanging indent or multiline-visual indent
-  depending on the size and shape of the arguments and what makes more sense to
-  the author. In other words, both this::
 
       print("I am a fish %s" % "moo")
 
@@ -33,17 +20,53 @@
 
         print(
             "I am a fish %s" %
-        "moo"
+            "moo",
         )
 
     ...are valid, although given each one takes up 2x more vertical space than
-  the previous, it's up to the author's discretion as to which layout makes most
+    the previous, it's up to the author's discretion as to which layout makes
-  sense for their function invocation.  (e.g. if they want to add comments
+    most sense for their function invocation.  (e.g. if they want to add
-  per-argument, or put expressions in the arguments, or group related arguments
+    comments per-argument, or put expressions in the arguments, or group
-  together, or want to deliberately extend or preserve vertical/horizontal
+    related arguments together, or want to deliberately extend or preserve
-  space)
+    vertical/horizontal space)
 
-- Comments should follow the `google code style
+- **Line length**:
+
+  Max line length is 79 chars (with flexibility to overflow by a "few chars" if
+  the overflowing content is not semantically significant and avoids an
+  explosion of vertical whitespace).
+
+  Use parentheses instead of ``\`` for line continuation where ever possible
+  (which is pretty much everywhere).
+
+- **Naming**:
+
+  - Use camel case for class and type names
+  - Use underscores for functions and variables.
+
+- Use double quotes ``"foo"`` rather than single quotes ``'foo'``.
+
+- **Blank lines**:
+
+  - There should be max a single new line between:
+
+    - statements
+    - functions in a class
+
+  - There should be two new lines between:
+
+    - definitions in a module (e.g., between different classes)
+
+- **Whitespace**:
+
+  There should be spaces where spaces should be and not where there shouldn't
+  be:
+
+  - a single space after a comma
+  - a single space before and after for '=' when used as assignment
+  - no spaces before and after for '=' for default values and keyword arguments.
+
+- **Comments**: should follow the `google code style
   <http://google.github.io/styleguide/pyguide.html?showone=Comments#Comments>`_.
   This is so that we can generate documentation with `sphinx
   <http://sphinxcontrib-napoleon.readthedocs.org/en/latest/>`_. See the