Add a docs section for all scripts.

docs/conf.py

@@ -18,6 +18,7 @@
 from unittest.mock import MagicMock
 
 import sphinx_rtd_theme
+from sphinx.ext import autodoc
 
 Mock = MagicMock
 
@@ -346,5 +347,19 @@ def maybe_skip_member(app, what, name, obj, skip, options):
         return skip
 
 
+class SimpleDocumenter(autodoc.MethodDocumenter):
+    """Used to extract literal docstrings.
+    """
+    objtype = "simple"
+
+    content_indent = u'    '
+
+    def add_directive_header(self, sig):
+        sourcename = self.get_sourcename()
+        self.add_line(u'::\n', sourcename)
+        pass
+
+
 def setup(app):
     app.connect('autodoc-skip-member', maybe_skip_member)
+    app.add_autodocumenter(SimpleDocumenter)

docs/index.rst

@@ -68,8 +68,9 @@ application.
   user/installation
   user/tutorial
   user/deployment
-  user/upgrading
   user/web-service
+  user/scripts
+  user/upgrading
   user/R
   user/julia
   user/faq

docs/user/deployment.rst

@@ -1,3 +1,5 @@
+.. _deployment:
+
 ============
  Deployment
 ============

docs/user/scripts.rst

@@ -0,0 +1,72 @@
+.. commands:
+
+=======
+Scripts
+=======
+
+Palladium includes a number of command-line scripts, many of which you
+may have already encountered in the :ref:`tutorial`.
+
+.. contents::
+   :local:
+
+pld-fit: *train models*
+=======================
+
+.. autosimple:: palladium.fit.fit_cmd
+
+.. seealso::
+
+   - :ref:`tutorial-run`
+
+pld-test: *test models*
+=======================
+
+.. autosimple:: palladium.eval.test_cmd
+
+.. seealso::
+
+   - :ref:`tutorial-run`
+
+pld-devserver: *serve the web API*
+==================================
+
+.. autosimple:: palladium.server.devserver_cmd
+
+.. seealso::
+
+   - :ref:`tutorial-run`
+   - :ref:`deployment`
+
+pld-grid-search: *find optimal hyperparameters*
+===============================================
+
+.. autosimple:: palladium.fit.grid_search_cmd
+
+.. seealso::
+
+   - :ref:`tutorial-grid-search`
+
+pld-list: *list available models*
+=================================
+
+.. autosimple:: palladium.eval.list_cmd
+
+pld-activate: *activate an available model*
+===========================================
+
+.. autosimple:: palladium.fit.activate_cmd
+
+pld-version: *display version number*
+=====================================
+
+.. autosimple:: palladium.util.version_cmd
+
+pld-upgrade: *upgrade database*
+===============================
+
+.. autosimple:: palladium.util.upgrade_cmd
+
+.. seealso::
+
+   - :ref:`upgrading`

docs/user/tutorial.rst

@@ -8,6 +8,8 @@ Tutorial
    :local:
 
 
+.. _tutorial-run:
+
 Run the Iris example
 ====================
 
@@ -258,6 +260,8 @@ out different values for *C*.  Can you find a setting for *C* that
 produces better accuracy?
 
 
+.. _tutorial-grid-search:
+
 Grid search
 -----------
 

palladium/eval.py

@@ -36,9 +36,13 @@ def test(dataset_loader_test, model_persister, model_version=None):
 
 
 def test_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
+    """\
 Test a model.
 
+Uses 'dataset_loader_test' and 'model_persister' from the
+configuration to load a test dataset to test the accuracy of a trained
+model with.
+
 Usage:
   pld-test [options]
 
@@ -48,7 +52,7 @@ def test_cmd(argv=sys.argv[1:]):  # pragma: no cover
   --model-version=<version>  The version of the model to be tested. If
                              not specified, the newest model will be used.
 """
-    arguments = docopt(__doc__, argv=argv)
+    arguments = docopt(test_cmd.__doc__, argv=argv)
     model_version = arguments['--model-version']
     model_version = int(model_version) if model_version is not None else None
     initialize_config(__mode__='fit')
@@ -64,15 +68,18 @@ def list(model_persister):
 
 
 def list_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
+    """\
 List information about available models.
 
+Uses the 'model_persister' from the configuration to display a list of
+models and their metadata.
+
 Usage:
   pld-list [options]
 
 Options:
   -h --help                  Show this screen.
 """
-    docopt(__doc__, argv=argv)
+    docopt(list_cmd.__doc__, argv=argv)
     initialize_config(__mode__='fit')
     list()

palladium/fit.py

@@ -68,9 +68,13 @@ def fit(dataset_loader_train, model, model_persister, persist=True,
 
 
 def fit_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
+    """\
 Fit a model and save to database.
 
+Will use 'dataset_loader_train', 'model', and 'model_perister' from
+the configuration file, to load a dataset to train a model with, and
+persist it.
+
 Usage:
   pld-fit [options]
 
@@ -87,7 +91,7 @@ def fit_cmd(argv=sys.argv[1:]):  # pragma: no cover
 
   -h --help                 Show this screen.
 """
-    arguments = docopt(__doc__, argv=argv)
+    arguments = docopt(fit_cmd.__doc__, argv=argv)
     no_save = arguments['--no-save']
     no_activate = arguments['--no-activate']
     save_if_better_than = arguments['--save-if-better-than']
@@ -110,16 +114,21 @@ def activate(model_persister, model_version):
 
 
 def activate_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
+    """\
 Activate the model with the given version.
 
+Models are usually made active right after fitting (see command
+pld-fit).  This command allows you to explicitly set the currently
+active model.  Use pld-list to get an overview of all available models
+along with their version identifiers.
+
 Usage:
   pld-activate <version> [options]
 
 Options:
   -h --help                 Show this screen.
 """
-    arguments = docopt(__doc__, argv=argv)
+    arguments = docopt(activate_cmd.__doc__, argv=argv)
     initialize_config(__mode__='fit')
     activate(model_version=int(arguments['<version>']))
 
@@ -154,15 +163,19 @@ def grid_search(dataset_loader_train, model, grid_search):
 
 
 def grid_search_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
+    """\
 Grid search parameters for the model.
 
+Uses 'dataset_loader_train', 'model', and 'grid_search' from the
+configuration to load a training dataset, and run a grid search on the
+model using the grid of hyperparameters.
+
 Usage:
   pld-grid-search [options]
 
 Options:
   -h --help                Show this screen.
 """
-    docopt(__doc__, argv=argv)
+    docopt(grid_search_cmd.__doc__, argv=argv)
     initialize_config(__mode__='fit')
     grid_search()

palladium/server.py

@@ -236,22 +236,22 @@ def alive(alive=None):
 
 
 def devserver_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
-Run a server for development.
+    """\
+Serve the web API for development.
 
 Usage:
   pld-devserver [options]
 
 Options:
-  -h --help                  Show this screen.
+  -h --help               Show this screen.
 
   --host=<host>           The host to use [default: 0.0.0.0].
 
   --port=<port>           The port to use [default: 5000].
 
   --debug=<debug>         Whether or not to use debug mode [default: 0].
 """
-    arguments = docopt(__doc__, argv=argv)
+    arguments = docopt(devserver_cmd.__doc__, argv=argv)
     initialize_config()
     app.run(
         host=arguments['--host'],

palladium/util.py

@@ -284,7 +284,7 @@ def memory_usage_psutil():
 
 
 def version_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
+    """\
 Print the version number of Palladium.
 
 Usage:
@@ -293,7 +293,7 @@ def version_cmd(argv=sys.argv[1:]):  # pragma: no cover
 Options:
   -h --help                Show this screen.
 """
-    docopt(__doc__, argv=argv)
+    docopt(version_cmd.__doc__, argv=argv)
     print(__version__)
 
 
@@ -306,23 +306,22 @@ def upgrade(model_persister, from_version=None, to_version=None):
 
 
 def upgrade_cmd(argv=sys.argv[1:]):  # pragma: no cover
-    __doc__ = """
+    """\
 Upgrade the database to the latest version.
 
 Usage:
   pld-ugprade [options]
 
 Options:
-
   --from=<v>               Upgrade from a specific version, overriding
                            the version stored in the database.
 
   --to=<v>                 Upgrade to a specific version instead of the
-                           latest version ({version}).
+                           latest version.
 
   -h --help                Show this screen.
-""".format(version=__version__)
-    arguments = docopt(__doc__, argv=argv)
+"""
+    arguments = docopt(upgrade_cmd.__doc__, argv=argv)
     initialize_config(__mode__='fit')
     upgrade(from_version=arguments['--from'], to_version=arguments['--to'])