updates to docs for core

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
 ----------------------
 
@@ -89,3 +156,17 @@ the CLI:
 * ``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/>`_.