misc software stuff

1 files changed, 59 insertions, 0 deletions

diff --git a/software/python.page b/software/python.page
index 261ba93..116ec6a 100644
--- a/software/python.page
+++ b/software/python.page
@@ -8,3 +8,62 @@ iPython tricks
 Use the ``cpaste'' command to copy in blocks of raw python code, even if the
 indenting is a little weird. 
 
+Style
+-------
+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 or at least pylint -r no.
+
+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,
+below any hashbang) docstring.
+
+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:
+
+    def public_fn_with_googley_docstring(name, state=None):
+        """This function does something.
+
+        Args:
+            name (str):  The name to use.
+
+        Kwargs:
+            state (bool): Current state to be in.
+
+        Returns:
+            int.  The return code::
+
+                0 -- Success!
+                1 -- No good.
+                2 -- Try again.
+
+        Raises:
+            AttributeError, KeyError
+
+        A really great idea.  A way you might use me is
+
+        >>> print public_fn_with_googley_docstring(name='foo', state=None)
+        0
+
+        BTW, this always returns 0.  **NEVER** use with :class:`MyPublicClass`.
+
+        """
+        return 0
+
+Packaging
+-----------
+
+Flask app packaging advice, including ``MANIFEST.in`` and non-PyPi dependancy
+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)).