Merge pull request #3 from dwhswenson/docs

Docs, READMEs, etc.

Author: dwhswenson

.coveragerc

@@ -0,0 +1,11 @@
+[report]
+omit =
+    */python?.?/*
+    */openpathsampling/*
+    */paths_cli/version.py
+    */paths_cli/_installed_version.py
+    */paths_cli/tests/*
+exclude_lines =
+    no-cov
+    def __repr__
+    raise NotImplementedError

.gitignore

@@ -1,5 +1,6 @@
 *.nc
 _installed_version.py
+*.swp
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -0,0 +1,71 @@
+# OpenPathSampling CLI
+
+*The command line interface to OpenPathSampling*
+
+OpenPathSampling is a powerful and flexible library for path sampling
+simulations. However, many users would prefer to interact with an executable on
+the command line, instead of writing everything in their own Python script.
+Here is that command line tool, including some useful scripts for dealing with
+OPS output files.
+
+The CLI is used as a single executable, `openpathsampling`, with multiple
+subcommands. We recommend aliasing `openpathsampling` to something simpler (maybe `ops`?) to save typing!
+
+Current categories of subcommands are for simulation running, and for
+miscellaneous operations on OPS output files.
+
+**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
+* `strip-snapshots`:  Remove coordinates/velocities from an OPS storage
+* `append`:           add objects from INPUT_FILE  to another file
+
+Full documentation is at ???; a brief summary is below.
+
+
+<!-- TODO: add TOC if the contents here get too long
+Contents:
+
+* Installation
+* Workflow
+* Creating your own commands 
+-->
+
+## Installation
+
+The OPS CLI can be installed with either ``conda`` or ``pip``:
+
+```bash
+conda -c conda-forge install openpathsampling-cli
+# or
+pip install openpathsampling-cli
+```
+
+Note that installing the CLI will also install OpenPathSampling, if you don't
+already have it.
+
+## Workflow
+
+**Set up, *then* simulate!** The overall idea is that you will first set up your
+simulation, and then use these scripts to run the resulting simulation setup
+files. Currently, writing a Python script (or better, using a Jupyter notebook
+to set things up interactively) is the best way to do that. Save the necessary
+simulation objects to a `setup.nc` file, and then use these scripts to run the
+simulation.
+
+## Creating your own commands
+
+Creating your own commands is extremely easy. The OPS CLI uses a plug-in
+architecture so that installing your own commands is as easy as putting a
+Python file in your `~/.openpathsampling/cli-plugins/` directory. 
+We provide a standard set of parameters as decorators, which can (and should)
+be re-used to load things from storage. The CLI is built on
+[`click`](https://click.palletsprojects.com/), so additional arguments are
+easily added using functionality from `click`. See our developer documentation
+for details.

docs/.gitignore

@@ -0,0 +1 @@
+parameter_table.rst

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,62 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('./sphinx-helpers'))
+
+# -- Preprocessing -----------------------------------------------------------
+
+from make_param_table import main as make_param_main
+with open("parameter_table.rst", mode='w') as f:
+    make_param_main(f)
+
+# -- Project information -----------------------------------------------------
+
+project = 'OpenPathSampling CLI'
+copyright = '2019-2020, David W.H. Swenson'
+author = 'David W.H. Swenson'
+
+# The full version, including alpha/beta/rc tags
+# TODO: get this from the release like other projects do
+release = '0.0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx_click.ext',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/for_core/README.md

@@ -0,0 +1 @@
+This is stuff that really should go into the OPS core docs.

docs/for_core/cli.rst

@@ -0,0 +1,88 @@
+.. _cli:
+
+Command Line Interface
+======================
+
+A separate command line tool for OpenPathSamplng can be installed. It is
+available via either ``conda`` (channel ``conda-forge``) or ``pip``, with
+the package name ``openpathsampling-cli``.
+
+Once you install this, you'll have access to the command
+``openpathsampling`` in your shell (although we recommend aliasing that to
+either ``paths`` or ``ops`` -- save yourself some typing!)
+
+This command is a gateway to many subcommands, just like ``conda`` and
+``pip`` (which have subcommands such as ``install``) or ``git`` (which has
+subcommands such as ``clone`` or ``commit``). You can get a full listing all
+the subcommands with ``openpathsampling --help``. For more information on
+any given subcommand, use ``openpathsampling SUBCOMMAND --help``, replacing
+``SUBCOMMAND`` with the subcommand you're interested in.
+
+Here, we will provide a description of a few of the subcommands that the CLI
+tool provides. This documentation may not be fully up-to-date with the more
+recent releases of the CLI, so use the CLI help tools to get a fuller
+understanding of what is included.
+
+For more details on how the CLI interprets its arguments, and to learn how
+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:
+
+Workflow with the CLI
+---------------------
+
+As always, the process of running a simulation is (1) set up the simulation;
+(2) run the simulation; (3) analyze the simulation. The CLI is mainly
+focused on step 2, although it also has tools that generally help with OPS
+files.
+
+To use it, you'll want to first set up 
+
+Simulation Commands
+-------------------
+
+One of the main concepts when working with the CLI is that you can create
+all the OPS simulation objects without running the simulation, save them in
+an OPS storage file, and then load them again to actually run your
+simulation. For simulation commands, the options all deal with loading
+simulation objects from storage.
+
+The simulation commands include ``equilibration``, ``pathsampling``, and
+``simulation``.  These commands aren'y necessarily mutually exclusive: you
+can accomplish an equilibration phase with any of them. The ``simulation``
+command is the most general; if you've any :class:`.PathSimulator` object,
+???
+
+Here are some of the simulation commands implemented in the OPS CLI:
+
+* ``pathsampling``: run path sampling with a given move scheme (suitable for
+  custom TPS schemes as well as TIS/RETIS); must provide move scheme,
+  iniital conditions,  and number of MC steps on command line
+* ``simulation``: run arbitrary OPS simulator (including committor and
+  related); must provide a simulator object and number of steps on the
+  command line
+* ``visit-all``: create initial trajectories by running MD until all states
+  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
+----------------------
+
+Even for users who prefer to develop their OPS projects entirely in Python,
+foregoing the CLI tools to run simulations, some of the "miscellaneous"
+commands are likely to be quite useful. Here are some that are available in
+the CLI:
+
+* ``nclist``: 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

docs/full_cli.rst

@@ -0,0 +1,14 @@
+.. _full_cli:
+
+Full CLI
+========
+
+This is a full description of the commands available in the CLI,
+automatically generated from the help for each command. Note that this
+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
+   :prog: openpathsampling
+   :show-nested:

docs/index.rst

@@ -0,0 +1,64 @@
+.. OpenPathSampling CLI documentation master file, created by
+   sphinx-quickstart on Sun Dec  8 01:32:00 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+OpenPathSampling CLI
+====================
+
+This is documentation for the OpenPathSampling CLI. Most of this is intended
+for developers. Basic usage documentation is the in the main OPS docs,
+although a few things here might be relevant to users (e.g., the details
+of how the built-in parameters interpret user-provided arguments, discussed
+in :ref:`interpretation`, or the :ref:`full listing for CLI commands and
+arguments <full_cli>`).
+
+The main purpose of this documentation is for people who want to create
+their own plugins for the OpenPathsampling CLI. Note that, because the OPS
+CLI uses a flexible dynamic plugin structure, installing a plugin is as easy
+as adding the plugin file to ``~/.openpathsampling/cli-plugins/``. See also
+:ref:`plugins`.
+
+Developing for the OPS CLI is pretty easy. The mains ideas are:
+
+* **Most of the business logic is elsewhere.** There shouldn't be anything
+  in this repository that involved putting together new move types or
+  anything like that. All of that belongs in external repositories (such as
+  OPS itself). All functionality in the CLI should be available in a
+  library; the CLI is a thin wrapper over the library.
+* **Reuse existing parameters whenever possible.** This ensures that
+  option labels and help strings are constant across the suite of
+  tools. It also ensures that behavior remains consistent: for example, the
+  steps that we go through in searching for an initial trajectory is the
+  same regardless of the type of simulation.
+
+
+A note on testing:
+
+Because the CLI is a thin wrapper over the library, we can also be
+relatively lax in testing. We thoroughly test the OPS loading parameters.
+But the actual commands are just chaining together existing well-tested OPS
+functions, and so we just do smoke tests for the commands.
+
+Essentially, the testing purpose that these serve would be as system tests
+for OPS, and OPS already has system tests. So we smoke test to make sure the
+code is sane. Again, this is only acceptable because the commands are thin
+wrappers around well-tested OPS code.
+
+.. note::
+
+   The project is called OpenPathSampling CLI, and the packages (PyPI and
+   conda-forge) are called ``openpathsampling-cli``. However, the name you
+   use to import the package is ``paths_cli``, as a nod to the encouraged
+   habit of importing openpathsampling as ``paths``.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   interpretation
+   plugins
+   parameters
+   workflows
+   full_cli
+