From 8e14aa80ee2ea6546bd659a03813db44bd9f0024 Mon Sep 17 00:00:00 2001
From: Alexander Graf <ghostwheel42@users.noreply.github.com>
Date: Fri, 4 Sep 2020 12:57:40 +0200
Subject: [PATCH] documented options and added help text

---
 core/admin/mailu/manage.py | 10 +++++-----
 docs/cli.rst               | 40 +++++++++++++++++++++++++++++++++-----
 2 files changed, 40 insertions(+), 10 deletions(-)

diff --git a/core/admin/mailu/manage.py b/core/admin/mailu/manage.py
index c36f45c0..b25ab568 100644
--- a/core/admin/mailu/manage.py
+++ b/core/admin/mailu/manage.py
@@ -180,9 +180,9 @@ yaml_sections = [
 ]
 
 @mailu.command()
-@click.option('-v', '--verbose', is_flag=True)
-@click.option('-d', '--delete-objects', is_flag=True)
-@click.option('-n', '--dry-run', is_flag=True)
+@click.option('-v', '--verbose', is_flag=True, help='Increase verbosity')
+@click.option('-d', '--delete-objects', is_flag=True, help='Remove objects not included in yaml')
+@click.option('-n', '--dry-run', is_flag=True, help='Perform a trial run with no changes made')
 @flask_cli.with_appcontext
 def config_update(verbose=False, delete_objects=False, dry_run=False, file=None):
     """sync configuration with data from YAML-formatted stdin"""
@@ -299,8 +299,8 @@ def config_update(verbose=False, delete_objects=False, dry_run=False, file=None)
 
 
 @mailu.command()
-@click.option('-f', '--full', is_flag=True)
-@click.option('-s', '--secrets', is_flag=True)
+@click.option('-f', '--full', is_flag=True, help='Include default attributes')
+@click.option('-s', '--secrets', is_flag=True, help='Include secrets (plain-text / not hashed)')
 @flask_cli.with_appcontext
 def config_dump(full=False, secrets=False):
     """dump configuration as YAML-formatted data to stdout"""
diff --git a/docs/cli.rst b/docs/cli.rst
index 64a4b17a..0036e504 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -73,8 +73,22 @@ config-dump
 -----------
 
 The purpose of this command is to dump domain-, relay-, alias- and user-configuration to a YAML template.
-If you want to export non-hashed secrets you have to add the ``--secrets`` option.
-Only non-default options are dumped. If you want to dump all options use ``--full``.
+
+.. code-block:: bash
+
+  # docker-compose exec admin flask mailu config-dump --help
+
+  Usage: flask mailu config-dump [OPTIONS]
+
+    dump configuration as YAML-formatted data to stdout
+
+  Options:
+    -f, --full     Include default attributes
+    -s, --secrets  Include secrets (plain-text / not hashed)
+    --help         Show this message and exit.
+
+If you want to export secrets (plain-text / not hashed) you have to add the ``--secrets`` option.
+Only non-default attributes are dumped. If you want to dump all attributes use ``--full``.
 
 .. code-block:: bash
 
@@ -85,13 +99,29 @@ config-update
 
 The purpose of this command is for importing domain-, relay-, alias- and user-configuration in bulk and synchronizing DB entries with an external YAML template.
 
+.. code-block:: bash
+
+  # docker-compose exec admin flask mailu config-update --help
+
+  Usage: flask mailu config-update [OPTIONS]
+
+    sync configuration with data from YAML-formatted stdin
+
+  Options:
+    -v, --verbose         Increase verbosity
+    -d, --delete-objects  Remove objects not included in yaml
+    -n, --dry-run         Perform a trial run with no changes made
+    --help                Show this message and exit.
+
+
+The current version of docker-compose exec does not pass stdin correctly, so you have to user docker exec instead:
+
 .. code-block:: bash
 
   docker exec -i $(docker-compose ps -q admin) flask mailu config-update -nvd < mail-config.yml
 
-*(The current version of docker-compose exec does not pass stdin correctly, so you have to user docker exec)*
 
-mail-config.yml looks like:
+mail-config.yml looks like this:
 
 .. code-block:: yaml
  
@@ -116,7 +146,7 @@ mail-config.yml looks like:
 
 You can use ``--dry-run`` to test your YAML without comitting any changes to the database.
 With ``--verbose`` config-update will show exactly what it changes in the database.
-Without ``--delete-object`` option config-update will only add/update new values but will *not* remove any entries missing in provided YAML input.
+Without ``--delete-object`` option config-update will only add/update changed values but will *not* remove any entries missing in provided YAML input.
 
 This is a complete YAML template with all additional parameters that could be defined: