PEP 7: Remove Python 2.2 advice, add C syntax highlighting and green/red sidebars (#3702)

Author: hugovk

peps/pep-0007.rst

@@ -1,14 +1,12 @@
 PEP: 7
 Title: Style Guide for C Code
-Version: $Revision$
-Last-Modified: $Date$
 Author: Guido van Rossum <[email protected]>, Barry Warsaw <[email protected]>
 Status: Active
 Type: Process
-Content-Type: text/x-rst
 Created: 05-Jul-2001
 Post-History:
 
+.. highlight:: c
 
 Introduction
 ============
@@ -77,36 +75,51 @@ Code lay-out
 
 * Function definition style: function name in column 1, outermost
   curly braces in column 1, blank line after local variable
-  declarations.  ::
+  declarations.
 
-      static int
-      extra_ivars(PyTypeObject *type, PyTypeObject *base)
-      {
-          int t_size = PyType_BASICSIZE(type);
-          int b_size = PyType_BASICSIZE(base);
+  .. code-block::
+     :class: good
 
-          assert(t_size >= b_size); /* type smaller than base! */
-          ...
-          return 1;
-      }
+     static int
+     extra_ivars(PyTypeObject *type, PyTypeObject *base)
+     {
+         int t_size = PyType_BASICSIZE(type);
+         int b_size = PyType_BASICSIZE(base);
+
+         assert(t_size >= b_size); /* type smaller than base! */
+         ...
+         return 1;
+     }
 
 * Code structure: one space between keywords like ``if``, ``for`` and
   the following left paren; no spaces inside the paren; braces are
   required everywhere, even where C permits them to be omitted, but do
   not add them to code you are not otherwise modifying.  All new C
-  code requires braces.  Braces should be formatted as shown::
+  code requires braces.  Braces should be formatted as shown:
+
+  .. code-block::
+     :class: good
+
+     if (mro != NULL) {
+         ...
+     }
+     else {
+         ...
+     }
+
+* The return statement should *not* get redundant parentheses:
+
+  .. code-block::
+     :class: bad
 
-      if (mro != NULL) {
-          ...
-      }
-      else {
-          ...
-      }
+     return(albatross); /* incorrect */
 
-* The return statement should *not* get redundant parentheses::
+  Instead:
 
-      return albatross; /* correct */
-      return(albatross); /* incorrect */
+  .. code-block::
+     :class: good
+
+     return albatross; /* correct */
 
 * Function and macro call style: ``foo(a, b, c)`` -- no space before
   the open paren, no spaces inside the parens, no spaces before
@@ -118,39 +131,48 @@ Code lay-out
 
 * Breaking long lines: if you can, break after commas in the outermost
   argument list.  Always indent continuation lines appropriately,
-  e.g.::
+  e.g.:
+
+  .. code-block::
+     :class: good
 
-      PyErr_Format(PyExc_TypeError,
-                   "cannot create '%.100s' instances",
-                   type->tp_name);
+     PyErr_Format(PyExc_TypeError,
+                  "cannot create '%.100s' instances",
+                  type->tp_name);
 
 * When you break a long expression at a binary operator, the
   operator goes at the end of the previous line, and braces should be
-  formatted as shown.  E.g.::
+  formatted as shown.  E.g.:
 
-      if (type->tp_dictoffset != 0 && base->tp_dictoffset == 0 &&
-          type->tp_dictoffset == b_size &&
-          (size_t)t_size == b_size + sizeof(PyObject *))
-      {
-          return 0; /* "Forgive" adding a __dict__ only */
-      }
+  .. code-block::
+     :class: good
+
+     if (type->tp_dictoffset != 0 && base->tp_dictoffset == 0 &&
+         type->tp_dictoffset == b_size &&
+         (size_t)t_size == b_size + sizeof(PyObject *))
+     {
+         return 0; /* "Forgive" adding a __dict__ only */
+     }
 
 * Vertically align line continuation characters in multi-line macros.
 
 * Macros intended to be used as a statement should use the
   ``do { ... } while (0)`` macro idiom,
   without a final semicolon.
-  Example::
+  Example:
+
+  .. code-block::
+     :class: good
 
-      #define ADD_INT_MACRO(MOD, INT)                                   \
-          do {                                                          \
-              if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) {  \
-                  goto error;                                           \
-              }                                                         \
-          } while (0)
+     #define ADD_INT_MACRO(MOD, INT)                                   \
+         do {                                                          \
+             if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) {  \
+                 goto error;                                           \
+             }                                                         \
+         } while (0)
 
-      // To be used like a statement with a semicolon:
-      ADD_INT_MACRO(m, SOME_CONSTANT);
+     // To be used like a statement with a semicolon:
+     ADD_INT_MACRO(m, SOME_CONSTANT);
 
 * ``#undef`` file local macros after use.
 
@@ -160,15 +182,18 @@ Code lay-out
 * Comments go before the code they describe.
 
 * All functions and global variables should be declared static unless
-  they are to be part of a published interface
+  they are to be part of a published interface.
 
 * For external functions and variables, we always have a declaration
   in an appropriate header file in the "Include" directory, which uses
-  the ``PyAPI_FUNC()`` macro and ``PyAPI_DATA()`` macro, like this::
+  the ``PyAPI_FUNC()`` macro and ``PyAPI_DATA()`` macro, like this:
 
-      PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
+  .. code-block::
+     :class: good
 
-      PyAPI_DATA(PyTypeObject) PySuper_Type;
+     PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
+
+     PyAPI_DATA(PyTypeObject) PySuper_Type;
 
 
 Naming conventions
@@ -200,44 +225,44 @@ Documentation Strings
   to support building Python without docstrings (``./configure
   --without-doc-strings``).
 
-  For C code that needs to support versions of Python older than 2.3,
-  you can include this after including ``Python.h``::
-
-      #ifndef PyDoc_STR
-      #define PyDoc_VAR(name)         static char name[]
-      #define PyDoc_STR(str)          (str)
-      #define PyDoc_STRVAR(name, str) PyDoc_VAR(name) = PyDoc_STR(str)
-      #endif
-
 * The first line of each function docstring should be a "signature
   line" that gives a brief synopsis of the arguments and return value.
-  For example::
+  For example:
+
+  .. code-block::
+     :class: good
 
-      PyDoc_STRVAR(myfunction__doc__,
-      "myfunction(name, value) -> bool\n\n\
-      Determine whether name and value make a valid pair.");
+     PyDoc_STRVAR(myfunction__doc__,
+     "myfunction(name, value) -> bool\n\n\
+     Determine whether name and value make a valid pair.");
 
   Always include a blank line between the signature line and the text
   of the description.
 
-  If the return value for the function is always None (because there
+  If the return value for the function is always ``None`` (because there
   is no meaningful return value), do not include the indication of the
   return type.
 
 * When writing multi-line docstrings, be sure to always use backslash
   continuations, as in the example above, or string literal
-  concatenation::
+  concatenation:
 
-      PyDoc_STRVAR(myfunction__doc__,
-      "myfunction(name, value) -> bool\n\n"
-      "Determine whether name and value make a valid pair.");
+  .. code-block::
+     :class: good
 
-  Though some C compilers accept string literals without either::
+     PyDoc_STRVAR(myfunction__doc__,
+     "myfunction(name, value) -> bool\n\n"
+     "Determine whether name and value make a valid pair.");
 
-      /* BAD -- don't do this! */
-      PyDoc_STRVAR(myfunction__doc__,
-      "myfunction(name, value) -> bool\n\n
-      Determine whether name and value make a valid pair.");
+  Though some C compilers accept string literals without either:
+
+  .. code-block::
+     :class: bad
+
+     /* BAD -- don't do this! */
+     PyDoc_STRVAR(myfunction__doc__,
+     "myfunction(name, value) -> bool\n\n
+     Determine whether name and value make a valid pair.");
 
   not all do; the MSVC compiler is known to complain about this.
 
@@ -246,14 +271,3 @@ Copyright
 =========
 
 This document has been placed in the public domain.
-
-
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   coding: utf-8
-   End: