software/python: more style fixups

1 files changed, 24 insertions, 20 deletions

diff --git a/software/python.page b/software/python.page
index 538f73d..ca37287 100644
--- a/software/python.page
+++ b/software/python.page
@@ -15,23 +15,24 @@ indenting is a little weird.
 
 Style
 -------
-Python PEP-008 <http://www.python.org/dev/peps/pep-0008/>: Style Guide for
+`Python PEP-008 <http://www.python.org/dev/peps/pep-0008/>`_: Style Guide for
 Python Code
 
-pylint <http://pypi.python.org/pypi/pylint>, a Python syntax checker. Very
-verbose, use pylint -E (errors only) or at least pylint -r no (no report). Eg,
-"pylint -r no file.py -d W0614 -d C -d R".
+`pylint <http://pypi.python.org/pypi/pylint>`_, a Python syntax checker. Very
+verbose, use pylint -E (errors only) or at least ``pylint -r no`` (no report).
+Eg, ``pylint -r no file.py -d W0614 -d C -d R``.
 
 For docstring documentation, refer to
-PEP-257<http://www.python.org/dev/peps/pep-0257/> and the Sphinx
-documentation<http://packages.python.org/an_example_pypi_project/sphinx.html
- >; specifically, document script functionality in a top level (above imports,
+`PEP-257 <http://www.python.org/dev/peps/pep-0257/>`_ and the `Sphinx
+documentation
+<http://packages.python.org/an_example_pypi_project/sphinx.html>`_;
+specifically, document script functionality in a top level (above imports,
 below any hashbang) docstring.
 
-Use leading "#:" style comments to document important non-object/non-function
+Use leading ``#:`` style comments to document important non-object/non-function
 element definitions (eg, static variables) in a way that will get pulled out
 into Sphinx.  Use "Google-style" function argument/return documentation instead
-of "Sphinx style". For example:
+of "Sphinx style". For example::
 
     def public_fn_with_googley_docstring(name, state=None):
         """This function does something.
@@ -62,7 +63,8 @@ of "Sphinx style". For example:
         """
         return 0
 
-autopep8 is a tool to automatically pep8-ify a file:
+
+autopep8 is a tool to automatically pep8-ify a file. Use it like::
 
     sudo pip install autopep8
     autopep8 --in-place --select=W293,W191,W291 *.py
@@ -79,8 +81,8 @@ advice: http://flask.pocoo.org/docs/patterns/distribute/
 Use ``console_scripts`` in ``setup.py`` to install system-wide scripts:
 http://packages.python.org/distribute/setuptools.html#automatic-script-creation
 
-For debian packaging, use [stdeb](http://pypi.python.org/pypi/stdeb)
-(via [stackoverflow thread](http://stackoverflow.com/questions/7110604/standard-way-to-create-debian-packages-for-distributing-python-programs)).
+For debian packaging, use `stdeb <http://pypi.python.org/pypi/stdeb>`_
+(via `stackoverflow thread <http://stackoverflow.com/questions/7110604/standard-way-to-create-debian-packages-for-distributing-python-programs>`_).
 
 For notes on pip vs. setup.py dependencies:
 https://caremad.io/blog/setup-vs-requirement/
@@ -100,32 +102,34 @@ number (as an int).
 RunSnakeRun
 -------------
 
-$ python -m cProfile -o ./dump.profile myscript.py --script-option blah
-$ # run to completion or Ctrl-C, then
-$ runsnakerun ./dump.profile
+Example session::
+
+    $ python -m cProfile -o ./dump.profile myscript.py --script-option blah
+    $ # run to completion or Ctrl-C, then
+    $ runsnakerun ./dump.profile
 
 nosetests
 -------------
 
 To do minimal tests without wrapping everything in a class, import assert
-functions from nose.tools, eg:
+functions from nose.tools, eg::
 
     from nose.tools import assert_raises, assert_equal
 
-To do interactive pdb debugging, simply:
+To do interactive pdb debugging, simply::
 
     $ nosetests --pdb
-        # or sometimes:
+    # or sometimes:
     $ nosetests --pdb-failures
 
 
 pdb
 -------
-To debug a script (interactive prompt on exception):
+To debug a script (interactive prompt on exception)::
 
     python -m pdb myscript.py
 
-or in-line, always at a particular point:
+or in-line, always at a particular point::
 
     import pdb; pdb.set_trace()