API docs for propka

- use autosummary (with custom module template)
- updated module docs for all modules so that they are included
  with sphinx autodocs

propka/run.py

@@ -1,4 +1,15 @@
-"""Entry point for PROPKA script."""
+"""
+Script functionality
+====================
+
+The :mod:`run` module provides a high-level interface to PROPKA 3.
+
+The :program:`propka3` script consists of the :func:`main`
+function. If similar functionality is desired from a Python script
+(without having to call the :program:`propka` script itself) then the
+:func:`single` function can be used instead.
+
+"""
 import logging
 from propka.lib import loadOptions
 from propka.input import read_parameter_file, read_molecule_file
@@ -30,11 +41,18 @@ def single(pdbfile, optargs=None):
 
     Commandline options can be passed as a **list** in *optargs*.
 
-    .. rubric:: Example
+    Example
+    -------
+    Given an input file "protein.pdb", run the equivalent of ``propka3
+    --mutation=N25R/N181D -v --pH=7.2 protein.pdb`` as::
+
+       propka.run.single("protein.pdb",
+                         optargs=["--mutation=N25R/N181D", "-v", "--pH=7.2"])
+
+
+    .. todo::
+       Test :func:`single`, not sure if it is correctly processing ``pdbfile``.
 
-    ::
-       single("protein.pdb", optargs=["--mutation=N25R/N181D", "-v",
-              "--pH=7.2"])
     """
     optargs = optargs if optargs is not None else []
     options = loadOptions(*optargs)