--- a/doc/v2_planning/coding_style.txt	Wed Oct 06 10:49:00 2010 -0400
+++ b/doc/v2_planning/coding_style.txt	Wed Oct 06 15:20:24 2010 -0400
@@ -22,11 +22,15 @@
                 out which of two versions is most recent)
 
     * OD: I like always doing the following when subclassing
+
+.. code-block:: python
+
       a class A:
         class B(A):
             def __init__(self, b_arg_1, b_arg_2, **kw):
                 super(B, self).__init__(**kw)
                 ...
+
       The point here is that the constructor always allow for extra keyword
       arguments (except for the class at the very top of the hierarchy), which
       are automatically passed to the parent class.
@@ -65,9 +69,11 @@
      OD: That'd make sense. However, when I wrote the above I hadn't looked
          closely at PEP257 yet, and I just noticed the following official
          recommendation for one-line docstrings in it:
-            The docstring is a phrase ending in a period. It prescribes the
-            function or method's effect as a command ("Do this", "Return that"), not as a
-            description; e.g. don't write "Returns the pathname ...".
+
+             The docstring is a phrase ending in a period. It prescribes the
+             function or method's effect as a command ("Do this", "Return that"), not as a
+             description; e.g. don't write "Returns the pathname ...".
+
          Anyone knows which style is most popular in the open-source
          community?
      OD: In lab meeting Yoshua ruled out: it is a waste of time to even
@@ -97,6 +103,7 @@
      JB: I thought that these are nice:
          - "from foo import Bar" 
          - "from foo import Bar, Blah"
+
         What's wrong with them?  They keep the code listing short and readable.
         I would discourage these forms when symbols 'Bar' and 'Blah' are
         ambiguous, in which case the parent module prefix serves to disambiguate
@@ -204,23 +211,30 @@
 
    * If necessary, you can add an extra pair of parentheses around an
      expression, but sometimes using a backslash looks better.
-    --> I rarely find that backslash looks better. In most situations you can
-        get rid of them. Typically I prefer:
+     --> I rarely find that backslash looks better. In most situations you can
+     get rid of them. Typically I prefer:
+
+..code-block:: python
+
             if (cond_1 and
                 cond_2 and
                 cond_3):
-        to
+
+     to
+
+..code-block:: python
+
             if cond_1 and \
                cond_2 and \
                cond_3:
 
    * You should use two spaces after a sentence-ending period.
-    --> Looks weird to me.
-    (DWF: This is an old convention from the typewriter era. It has more
-    or less been wiped out by HTML's convention of ignoring extra 
-    whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for
-    more detail. I think it's okay to drop this convention in source code.)
-    OD: Cool, thanks, I guess we can drop it then.
+     --> Looks weird to me.
+     (DWF: This is an old convention from the typewriter era. It has more
+     or less been wiped out by HTML's convention of ignoring extra 
+     whitespace: see http://en.wikipedia.org/wiki/Sentence_spacing for
+     more detail. I think it's okay to drop this convention in source code.)
+     OD: Cool, thanks, I guess we can drop it then.
 
     * Missing in PEP 8:
         - How to indent multi-line statements? E.g. do we want
@@ -294,7 +308,7 @@
     * Which Python 2.x version do we want to support?
 
     * Is it reasonable to have coding guidelines that would make the code as
-compatible as possible with Python 3?
+      compatible as possible with Python 3?
 
 C coding style
 --------------
@@ -305,52 +319,52 @@
 ------------------
 
    * Coding guidelines
-PEP 8 & Google should be a good basis to start with.
-Task: Highlight the most important points in them (OD).
+     PEP 8 & Google should be a good basis to start with.
+     Task: Highlight the most important points in them (OD).
 
    * Documentation
-Use RST with Sphinx.
-Task: Provide specific examples on how to document a class, method, and some
-specific classes like Op (DE). Modify the theano documentation to include that.
-OD: May want to check out
-    http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
+     Use RST with Sphinx.
+     Task: Provide specific examples on how to document a class, method, and some
+     specific classes like Op (DE). Modify the theano documentation to include that.
+     OD: May want to check out
+     http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines
 
    * Python versions to be supported
-Support 2.4 (because some of the clusters are still running 2.4) and write
-code that can be converted to 3.x with 2to3 in a straightforward way.
-Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
+     Support 2.4 (because some of the clusters are still running 2.4) and write
+     code that can be converted to 3.x with 2to3 in a straightforward way.
+     Task: Write to-do's and to-not-do's to avoid compatibility issues. (OD)
 
    * C coding style
-How to write C code (in particular for Numpy / Cuda), and how to mix C and
-Python.
-Task: See if there would be a sensible C code style to follow (maybe look how
-Numpy does it), and how projects that mix C and Python deal with it (e.g. use
-separate files, or be able to have mixed syntax highlighting?) (FB)
+     How to write C code (in particular for Numpy / Cuda), and how to mix C and
+     Python.
+     Task: See if there would be a sensible C code style to follow (maybe look how
+     Numpy does it), and how projects that mix C and Python deal with it (e.g. use
+     separate files, or be able to have mixed syntax highlighting?) (FB)
 
    * Program output
-Use the warning and logging modules. Avoid print as much as possible.
-Task: Look into these modules to define general guidelines e.g. to decide when
-to use warning instead of logging. (DWF)
+     Use the warning and logging modules. Avoid print as much as possible.
+     Task: Look into these modules to define general guidelines e.g. to decide when
+     to use warning instead of logging. (DWF)
 
    * Automatized code verification
-Use pychecker & friends to make sure everything is fine.
-Task: Look into the various options available (DE)
-Result: See sections 'Tools to help us out' and 'Automating and enforcing coding
-style'
+     Use pychecker & friends to make sure everything is fine.
+     Task: Look into the various options available (DE)
+     Result: See sections 'Tools to help us out' and 'Automating and enforcing coding
+     style'
 
    * Tests
-Force people to write tests. Automatic email reminder of code lines not
-covered by tests (see if we can get this from nosetests). Decorator to mark
-some classes / methods as not being tested yet, so as to be able to
-automatically warn the user when he is using untested stuff (and to remind
-ourselves we should add a test).
-Task: See feasibility. (OD)
-Result: See section 'Enforcing strict testing policy'.
+     Force people to write tests. Automatic email reminder of code lines not
+     covered by tests (see if we can get this from nosetests). Decorator to mark
+     some classes / methods as not being tested yet, so as to be able to
+     automatically warn the user when he is using untested stuff (and to remind
+     ourselves we should add a test).
+     Task: See feasibility. (OD)
+     Result: See section 'Enforcing strict testing policy'.
 
    * VIM / Emacs plugins / config files
-To enforce good coding style automatically.
-Task: Look for existing options. (FB)
-(DWF: I have put some time into this for vim, I will send around my files)
+     To enforce good coding style automatically.
+     Task: Look for existing options. (FB)
+     (DWF: I have put some time into this for vim, I will send around my files)
 
 Suggestion by PV
 ----------------
@@ -420,28 +434,28 @@
 Dumi:
 
   * pylint: highly configurable and very popular tool, similar in spirit to lint
-  for C. Can specify a config file, customize/disable warnings and errors, hook
-  it to vim/emacs and include coding style convensions in the check too. A nice
-  feature is that you can include a comment like "# pylint: disable-msg=C0103"
-  into a file and disable a message locally. This is nice and dangerous at the
-  same time. Another cool feature is incremental checking with caching of
-  results, which also allows tracking of progress.
+    for C. Can specify a config file, customize/disable warnings and errors, hook
+    it to vim/emacs and include coding style convensions in the check too. A nice
+    feature is that you can include a comment like "# pylint: disable-msg=C0103"
+    into a file and disable a message locally. This is nice and dangerous at the
+    same time. Another cool feature is incremental checking with caching of
+    results, which also allows tracking of progress.
 
   * pyflakes: pylint alternative that is supposedly faster, but is I think more
-  limited in the number of things it is good at: "PyFlakes will tell you when
-  you have forgotten an import, mistyped a variable name, defined two functions
-  with the same name, shadowed a variable from another scope, imported a module
-  twice, or two different modules with the same name, and so on.". Most reviews
-  found online praise the speed, but note that pylint is clearly superior in
-  every other respect.
+    limited in the number of things it is good at: "PyFlakes will tell you when
+    you have forgotten an import, mistyped a variable name, defined two functions
+    with the same name, shadowed a variable from another scope, imported a module
+    twice, or two different modules with the same name, and so on.". Most reviews
+    found online praise the speed, but note that pylint is clearly superior in
+    every other respect.
 
   * pychecker: it actually *imports* each module (not sure if pylint does this).
-  It seems that pylint = pychecker + coding style and that pylint is more
-  popular.
+    It seems that pylint = pychecker + coding style and that pylint is more
+    popular.
 
   * pep8: if all you care is about obeying PEP-8:
-  http://pypi.python.org/pypi/pep8 (includes the actual PEP-8 snippets with the
-  errors found, which is neat). Otherwise, pylint seems like a superset of this. 
+    http://pypi.python.org/pypi/pep8 (includes the actual PEP-8 snippets with the
+    errors found, which is neat). Otherwise, pylint seems like a superset of this. 
 
   * http://www.doughellmann.com/articles/pythonmagazine/completely-different/2008-03-linters/index.html
   - article from 2008 comparing pylint, pychecker, and pyflakes. The conclusion
@@ -462,36 +476,36 @@
 Dumi: there are several ways of approaching this, independently of the tools used:
 
    * Create a precommit hook for mercurial, which runs the tool(s) of choice and
-   generates warnings or aborts the commit process. This hook is a simple Python
-   module (well, as simple as we want it to be), which we can include into
-   everyone's hgrc, in the precommit.pylint variable, for instance. An example
-   is http://github.com/jrburke/dvcs_jslint/blob/master/dvcs_jslint.js. The
-   advantage of this approach is that the load is distributed and
-   errors/warnings are caught client-side, before the commit.
+     generates warnings or aborts the commit process. This hook is a simple Python
+     module (well, as simple as we want it to be), which we can include into
+     everyone's hgrc, in the precommit.pylint variable, for instance. An example
+     is http://github.com/jrburke/dvcs_jslint/blob/master/dvcs_jslint.js. The
+     advantage of this approach is that the load is distributed and
+     errors/warnings are caught client-side, before the commit.
 
    * Another client-side option is to have editor plugins for the various style
-   checkers: vim and emacs can access pylint pretty easily for instance.
+     checkers: vim and emacs can access pylint pretty easily for instance.
 
    * Instead of doing this client-side, one can do things server-side. On
-   Assembla, this means using their Webhooks
-   (http://www.assembla.com/spaces/demostuff/webhook_tool), since HTTP-based
-   hooks that we would need to tie with our buildbot server (whichever server we
-   choose that to be).
+     Assembla, this means using their Webhooks
+     (http://www.assembla.com/spaces/demostuff/webhook_tool), since HTTP-based
+     hooks that we would need to tie with our buildbot server (whichever server we
+     choose that to be).
 
    * I (DE) prefer starting with the client-side approach, as it is easier to
-   implement, has no single point of failure and is deployable fast. We could
-   have a "batch" script that runs our lint tools in conjunction with hg
-   annotate and sends hate-mail once a week to offenders who have somehow
-   slipped things through the cracks. Also on the server-side we could run
-   time-consuming checking (though how such checks would differ from tests is
-   unclear).
+     implement, has no single point of failure and is deployable fast. We could
+     have a "batch" script that runs our lint tools in conjunction with hg
+     annotate and sends hate-mail once a week to offenders who have somehow
+     slipped things through the cracks. Also on the server-side we could run
+     time-consuming checking (though how such checks would differ from tests is
+     unclear).
 
 Note that:
 
   * I haven't found anything ready-made online, so we need to write these
-  hooks ourselves.
+    hooks ourselves.
   * I think we should make it so that it is not possible to commit things if
-  pylint reports an actual error.
+    pylint reports an actual error.
 
 Type checking
 -------------