update: command helptext

onyo/cli/init.py

@@ -39,22 +39,22 @@ def init(args: argparse.Namespace) -> None:
     r"""
     Initialize an Onyo repository.
 
-    The current working directory will be initialized if neither **DIR** nor the
+    The current working directory is initialized if neither **DIR** nor the
     ``onyo -C DIR`` flag are specified. If the target directory does not exist,
-    it will be created.
+    it is created.
 
     Initialization steps are:
 
       * create the target directory (if it does not exist)
       * initialize as a git repository (if it is not one already)
       * create the ``.onyo/`` directory, populate its contents, and commit
 
-    Init-ing non-empty directories and git repositories is allowed. Only the
-    ``.onyo`` directory will be committed. All other contents will be left in
-    their state.
+    Initializing non-empty directories and existing git repositories is allowed,
+    and only the ``.onyo/`` directory and its contents are committed. All other
+    contents are left in their state.
 
-    Repeatedly init-ing a repository will not alter the contents, and will exit
-    with an error.
+    Executing ``onyo init`` on an existing Onyo repository does not alter its
+    contents, and exits with an error.
     """
     target_dir = Path(args.directory).resolve() if args.directory else Path.cwd()
     OnyoRepo(target_dir, init=True)

onyo/cli/mkdir.py

@@ -52,11 +52,8 @@ def mkdir(args: argparse.Namespace) -> None:
     Intermediate directories are created as needed (i.e. parent and child
     directories can be created in one call).
 
-    An empty ``.anchor`` file is added to each directory, to ensure that git
-    tracks them even when empty.
-
-    If a **DIRECTORY** is already a directory or a protected path, then Onyo
-    will error and leave everything unmodified.
+    If **DIRECTORY** is already a directory or a protected path, then Onyo
+    errors and leaves everything unmodified.
     """
     dirs = [Path(d).resolve() for d in args.directory]
     inventory = Inventory(repo=OnyoRepo(Path.cwd(), find_root=True))

onyo/cli/mv.py

@@ -37,7 +37,7 @@
 epilog_mv = r"""
 .. rubric:: Examples
 
-Assign an asset:
+Assign an asset to a user:
 
 .. code:: shell
 
@@ -65,10 +65,10 @@
 
 def mv(args: argparse.Namespace) -> None:
     r"""
-    Move **SOURCE**\ s into the **DEST** directory, or rename **SOURCE** to **DEST**.
+    Move **SOURCE**\ s into the **DEST** directory, or rename a **SOURCE** directory to **DEST**.
 
-    If **DEST** is an Asset File, it will be converted into an Asset Directory
-    and then the **SOURCE**\ s will be moved into it.
+    If **DEST** is an Asset File it is converted into an Asset Directory and the
+    **SOURCE**\ s are moved into it.
 
     Assets cannot be renamed using ``onyo mv``. Their names are generated from
     keys in their contents. To rename a file, use ``onyo set`` or ``onyo edit``.

onyo/cli/rm.py

@@ -29,7 +29,7 @@
         default=False,
         action='store_true',
         help=r"""
-            Remove directories recursively including their content.
+            Remove directories and their contents recursively.
         """
     ),
 
@@ -51,18 +51,24 @@
 .. code:: shell
 
     $ onyo rm --message "Bob retired; he won at bingo" admin/Bingo\ Bob/
+
+Remove a building and all of its assets:
+
+.. code:: shell
+
+    $ onyo rm --recursive --message "The great fire..." buildings/20.3/
+
 """
 
 
 def rm(args: argparse.Namespace) -> None:
     r"""
     Delete **ASSET**\ s and/or **DIRECTORY**\ s.
 
-    Directories and asset directories are deleted along with their contents,
-    if the ``--recursive`` flag is set. Otherwise, fails on non-empty directories.
+    If ``--recursive`` is used, directories are deleted along with their
+    contents. Otherwise it fails on non-empty directories.
 
-    If any of the given paths are invalid, Onyo will error and delete none of
-    them.
+    If any of the given paths are invalid, Onyo errors and nothing is deleted.
     """
 
     inventory = Inventory(repo=OnyoRepo(Path.cwd(), find_root=True))

onyo/cli/rmdir.py

@@ -29,7 +29,7 @@
 epilog_rmdir = r"""
 .. rubric:: Examples
 
-Remove a user from a group:
+Remove an empty user directory:
 
 .. code:: shell
 
@@ -48,9 +48,9 @@ def rmdir(args: argparse.Namespace) -> None:
     r"""
     Delete **DIRECTORY**\ s or convert Asset Directories into Asset Files.
 
-    If the **DIRECTORY** is not empty, does not exist, the path is protected, or
-    the asset is already an Asset File, then Onyo will error and leave
-    everything unmodified.
+    If any **DIRECTORY** is not empty, does not exist, its path is protected, or
+    the asset is already an Asset File, then Onyo errors and leaves everything
+    unmodified.
     """
 
     dirs = [Path(d).resolve() for d in args.directory]

onyo/cli/tree.py

@@ -35,6 +35,13 @@
 .. code:: shell
 
     $ onyo tree shelf
+
+List only the room structure of a building:
+
+.. code:: shell
+
+    $ onyo tree --dirs-only building_3/
+
 """
 
 
@@ -45,8 +52,9 @@ def tree(args: argparse.Namespace) -> None:
     If no directory is provided, the tree for the current working directory is
     listed.
 
-    Directories are printed sequentially. If one does not exist, no further
-    trees will be printed and an error is returned.
+    **DIRECTORY**\ s are printed sequentially. If one does not exist, or is not
+    an inventory directory, no further trees will be printed and an error is
+    returned.
     """
     inventory = Inventory(repo=OnyoRepo(Path.cwd(), find_root=True))
     dirs = [(d, Path(d).resolve()) for d in args.directory]

onyo/cli/tsv_to_yaml.py

@@ -22,12 +22,13 @@
 epilog_tsv_to_yaml = r"""
 .. rubric:: Examples
 
+print a table's contents in the YAML format:
+
 .. code:: shell
 
     $ onyo tsv-to-yaml table.tsv
 
-The resulting multi-document YAML file can be split into multiple YAML files (if
-desired) using ``csplit``.
+Split the resulting multi-document YAML output into separate YAML documents:
 
 .. code:: shell
 
@@ -37,13 +38,14 @@
 
 def tsv_to_yaml(args: argparse.Namespace) -> None:
     r"""
-    Convert a TSV file into YAML suitable to pass to ``onyo new`` and ``onyo set``.
+    Print a TSV file's contents as YAML, suitable to pass into ``onyo new`` and ``onyo set``.
 
-    The header declares the key names to be populated. The values to populate
-    documents are declared with one line per YAML document.
+    The output is printed to stdout as a multi-document YAML file, and each
+    document is separated with a ``---`` line.
 
-    The output is printed to stdout as a multiple document YAML file (each
-    document is separated by a ``---`` line).
+    The TSV file's header row declares the key names for all resulting YAML
+    documents, and each row of the table declares the values for one of the
+    YAML documents.
     """
 
     onyo_tsv_to_yaml(tsv=Path(args.tsv[0]).resolve())

onyo/cli/unset.py

@@ -68,7 +68,7 @@ def unset(args: argparse.Namespace) -> None:
     configuration option) cannot be unset.
 
     The contents of all modified assets are checked for validity before
-    committing. If problems are found, Onyo will error and leave the assets
+    committing. If problems are found, Onyo errors and leaves the assets
     unmodified.
     """