summaryrefslogtreecommitdiffstats
path: root/software
diff options
context:
space:
mode:
authorbryan newbold <bnewbold@twinleaf.com>2015-08-19 15:21:46 -0700
committerbryan newbold <bnewbold@twinleaf.com>2015-08-19 15:26:37 -0700
commitceaa952f92a607b27c61b483051cd83ec5cfc41f (patch)
tree28b6d2066838bfdd75d3888d78c9fe227e74a222 /software
parent3a492dcd56c5f2f9c93f575662eae97de0be9416 (diff)
downloadknowledge-ceaa952f92a607b27c61b483051cd83ec5cfc41f.tar.gz
knowledge-ceaa952f92a607b27c61b483051cd83ec5cfc41f.zip
software/python: more style fixups
Diffstat (limited to 'software')
-rw-r--r--software/python.page44
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()