Merge pull request #18 from dwhswenson/fix_docs

Fix docs

Author: dwhswenson

docs/for_core/cli.rst

@@ -28,8 +28,8 @@ to develop plugins for the CLI, see its documentation.  The CLI subcommands
 are defined through a plugin system, which makes it very easy for developers
 to create new subcommands.
 
-* CLI documentation:
-* CLI code repository:
+* CLI documentation: https://openpathsampling-cli.readthedocs.io/
+* CLI code repository: https://github.com/openpathsampling/openpathsampling-cli/
 
 Workflow with the CLI
 ---------------------
@@ -41,6 +41,76 @@ files.
 
 To use it, you'll want to first set up 
 
+
+Finding your way around the CLI
+-------------------------------
+
+Like many command line tools, the OPS CLI has the options ``-h`` or
+``--help`` to get help. If you run ``openpathsampling --help`` you should
+see something like this::
+
+    Usage: openpathsampling [OPTIONS] COMMAND [ARGS]...
+
+      OpenPathSampling is a Python library for path sampling simulations. This
+      command line tool facilitates common tasks when working with
+      OpenPathSampling. To use it, use one of the subcommands below. For
+      example, you can get more information about the pathsampling tool with:
+
+          openpathsampling pathsampling --help
+
+    Options:
+      --log PATH  logging configuration file
+      -h, --help  Show this message and exit.
+
+    Simulation Commands:
+      visit-all     Run MD to generate initial trajectories
+      equilibrate   Run equilibration for path sampling
+      pathsampling  Run any path sampling simulation, including TIS variants
+
+    Miscellaneous Commands:
+      contents     list named objects from an OPS .nc file
+      append       add objects from INPUT_FILE  to another file
+
+The ``--log`` option takes a logging configuration file (e.g., `logging.conf
+<>`_, and sets that logging behavior. If you use it, it must come before the
+subcommand name.
+
+You can find out more about each subcommand by putting ``--help`` *after*
+the subcommand name, e.g., ``openpathsampling pathsampling --help``, which
+returns::
+
+    Usage: openpathsampling pathsampling [OPTIONS] INPUT_FILE
+
+      General path sampling, using setup in INPUT_FILE
+
+    Options:
+      -o, --output-file PATH  output ncfile  [required]
+      -m, --scheme TEXT       identifier for the move scheme
+      -t, --init-conds TEXT   identifier for initial conditions (sample set or
+                              trajectory)
+      -n, --nsteps INTEGER    number of Monte Carlo trials to run
+      -h, --help              Show this message and exit.
+
+Here you see the list of the options for the running a path sampling
+simulation. In general, path sampling requires an output
+file, a move scheme and initial conditions from some input file, and the
+number of steps to run.  Note that only the output file is technically
+required: the CLI will default to running 0 steps (essentially, testing the
+validity of your setup), and it can try to guess the move scheme and initial
+conditions.  In general, the way it guesses follows the following path:
+
+1. If there is only one object of the suitable type in the INPUT_FILE, use
+   that.
+2. If there are multiple objects of the correct type, but only one has a
+   name, use the named object.
+3. In special cases it looks for specific names, such as
+   ``initial_conditions``, and will use those.
+
+Full details on how various CLI parameters search the storage can be seen in
+the `Parameter Interpretation
+<https://openpathsampling-cli.readthedocs.io/en/latest/interpretation.html>`_
+section of the CLI docs.
+
 Simulation Commands
 -------------------
 
@@ -68,9 +138,6 @@ Here are some of the simulation commands implemented in the OPS CLI:
   have been visited (works for MSTIS or any 2-state system); must provide
   states, engine, and initial snapshot on command line
 
-.. TODO figure showing how these all work -- what is needed for each, what
-   is implicit
-
 Miscellaneous Commands
 ----------------------
 
@@ -81,11 +148,27 @@ the CLI:
 
 * ``contents``: list all the named objects in an OPS storage, organized by
   store (type); this is extremely useful to get the name of an object to use
-  as command-line input to one of the simulation scripts
+
+
 .. * ``strip-snapshots``: create a copy of the input storage file with the
   details (coordinates/velocities) of all snapshots removed; this allows you
   to make a much smaller copy (with results of CVs) to copy back to a local
   computer for analysis
+
 * ``append`` : add an object from once OPS storage into another one; this is
   useful for getting everything into a single file before running a
   simulation
+
+Customizing the CLI
+-------------------
+
+The OPS CLI uses a flexible plugin system to enable users to easily add
+custom functionality. This way, you can create and distribute custom
+plugins, giving more functionality to other users who would benefit from it,
+without adding everything to the core package and thus overwhelming new
+users.
+
+Installing a plugin is easy: just create the directory
+``$HOME/.openpathsampling/cli-plugins/``, and copy the plugin Python script
+into there. For details on how to write a CLI plugin, see the `CLI
+development docs <https://openpathsampling-cli.readthedocs.io/>`_.

docs/full_cli.rst

@@ -9,6 +9,6 @@ currently gives all commands alphabetically, without regard to section. In
 general, this is not yet well-organized; contributions to improve that would
 be appreciated.
 
-.. click:: paths_cli.cli:OPS_CLI
+.. click:: paths_cli.cli:main
    :prog: openpathsampling
    :show-nested:

docs/sphinx-helpers/make_param_table.py

@@ -12,6 +12,7 @@
 import click
 
 from paths_cli import parameters
+from  paths_cli import param_core
 
 TableEntry = collections.namedtuple("TableEntry",
                                     "param flags get_args help")
@@ -20,7 +21,7 @@ def is_click_decorator(thing):
     return getattr(thing, '__module__', None) == 'click.decorators'
 
 def is_parameter(thing):
-    return (isinstance(thing, parameters.AbstractLoader)
+    return (isinstance(thing, param_core.AbstractLoader)
             or is_click_decorator(thing))
 
 def rst_wrap(code):
@@ -33,18 +34,18 @@ def flags_help(click_decorator):
     return flags, help_
 
 def get_args(parameter):
-    if isinstance(parameter, parameters.StorageLoader):
+    if isinstance(parameter, param_core.StorageLoader):
         return "``name``"
-    elif isinstance(parameter, (parameters.OPSStorageLoadNames,
-                                parameters.OPSStorageLoadSingle)):
+    elif isinstance(parameter, (param_core.OPSStorageLoadNames,
+                                param_core.OPSStorageLoadSingle)):
         return "``storage``, ``name``"
     elif is_click_decorator(parameter):
         return "No ``get`` function"
     else:
         return "Unknown"
 
 def get_click_decorator(thing):
-    if isinstance(thing, parameters.AbstractLoader):
+    if isinstance(thing, param_core.AbstractLoader):
         return thing.param.clicked()
     elif is_click_decorator(thing):
         return thing

paths_cli/cli.py

@@ -146,4 +146,4 @@ def main(log):
     logger.debug("About to run command")  # TODO: maybe log invocation?
 
 if __name__ == '__main__':  # no-cov
-    cli()
+    main()