From 60133f69e16ae00eaeecae86e2b27ff85262844e Mon Sep 17 00:00:00 2001 From: Tobias Kadelka Date: Tue, 1 Apr 2025 15:17:49 +0200 Subject: [PATCH] update: command helptext https://github.com/psyinfra/onyo/issues/789 --- onyo/cli/init.py | 14 +++++++------- onyo/cli/mkdir.py | 7 ++----- onyo/cli/mv.py | 8 ++++---- onyo/cli/rm.py | 16 +++++++++++----- onyo/cli/rmdir.py | 8 ++++---- onyo/cli/tree.py | 12 ++++++++++-- onyo/cli/tsv_to_yaml.py | 16 +++++++++------- onyo/cli/unset.py | 2 +- 8 files changed, 48 insertions(+), 35 deletions(-) diff --git a/onyo/cli/init.py b/onyo/cli/init.py index f91590a7..e80f793b 100644 --- a/onyo/cli/init.py +++ b/onyo/cli/init.py @@ -39,9 +39,9 @@ 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: @@ -49,12 +49,12 @@ def init(args: argparse.Namespace) -> None: * 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) diff --git a/onyo/cli/mkdir.py b/onyo/cli/mkdir.py index a0f31b9a..3f498aa8 100644 --- a/onyo/cli/mkdir.py +++ b/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)) diff --git a/onyo/cli/mv.py b/onyo/cli/mv.py index 3d524f19..884ad42c 100644 --- a/onyo/cli/mv.py +++ b/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``. diff --git a/onyo/cli/rm.py b/onyo/cli/rm.py index 2e97b2e5..174569ff 100644 --- a/onyo/cli/rm.py +++ b/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,6 +51,13 @@ .. 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/ + """ @@ -58,11 +65,10 @@ 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)) diff --git a/onyo/cli/rmdir.py b/onyo/cli/rmdir.py index c159d89a..f9ce469d 100644 --- a/onyo/cli/rmdir.py +++ b/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] diff --git a/onyo/cli/tree.py b/onyo/cli/tree.py index 2852eb3c..07339401 100644 --- a/onyo/cli/tree.py +++ b/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] diff --git a/onyo/cli/tsv_to_yaml.py b/onyo/cli/tsv_to_yaml.py index d9fa79d4..df2f4592 100644 --- a/onyo/cli/tsv_to_yaml.py +++ b/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()) diff --git a/onyo/cli/unset.py b/onyo/cli/unset.py index f2bad6a7..4401ad65 100644 --- a/onyo/cli/unset.py +++ b/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. """