More details in commands and lineage

dataworkspaces/lineage.py

@@ -38,9 +38,11 @@
 * :class:`~ResourceRef` - A reference to a resource for use as a step input or output.
   A ResourceRef contains a resource name and an optional path within that resource.
   This lets you manage lineage down to the directory or even file level. The APIs also
-  support specifying a path o the local filesystem instead of a ResourceRef. This path
+  support specifying a path on the local filesystem instead of a ResourceRef. This path
   is automatically resolved to a ResourceRef (it must map to the a location under the
-  local path of a resource).
+  local path of a resource). By storing :class:`~ResourceRef`s instead of hard-coded
+  filesystem paths, we can include non-local resources (like an S3 bucket) and ensure
+  that the workspace is easily deployed on a new machine.
 * :class:`~Lineage` - The main lineage object, instantiated at the start of your step.
   At the beginning of your step, you specify the inputs, parameters, and outputs. At the
   end of the step, the data is saved, along with any results you might have from that step.

docs/commands.rst

@@ -3,6 +3,26 @@
 3. Command Reference
 ====================
 In this section, we describe the full command line interface for Data Workspaces.
+This interface is built around a script ``dws``, which is installed into your
+path when you install the ``dataworkspaces`` package. The overall interface
+for ``dws`` is::
+
+  dws [--batch] [--verbose] [--help] COMMAND [--help] [OPTIONS] [ARGS]...
+
+``dws`` has three options common to all commands:
+
+* ``--batch``, which runs the command in a mode that never asks for user confirmation and
+  will error out if it absolutely requires an input (useful for automation),
+* ``--verbose``, which will print a lot of detail about what will be and has been done for a command
+  (useful for debugging), and
+* ``--help``, which prints these common options and a list of available commands.
+
+Next on your command line comes the command name (e.g. ``init``, ``clone``, ``snapshot``).
+Each command has its own arguments and options, as documented below.
+All commands take a ``--help`` argument, which will print the specific options and
+arguments for the command. Finally,
+the ``add`` subcommand has further subcommands, representing the
+individual resource types (e.g. `git`, `local-files`, `rclone`).
 
 .. click:: dataworkspaces.dws:cli
    :prog: dws