From ee92fc6907be10e231f9243556309486a96f4785 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gina=20H=C3=A4u=C3=9Fge?= <osd@foosel.net>
Date: Fri, 14 Oct 2016 13:57:01 +0200
Subject: [PATCH] Docs for CLI of software update plugin

---
 docs/bundledplugins/softwareupdate.rst      | 60 +++++++++++++++++++++
 src/octoprint/plugins/softwareupdate/cli.py | 38 ++++++++++++-
 2 files changed, 96 insertions(+), 2 deletions(-)

diff --git a/docs/bundledplugins/softwareupdate.rst b/docs/bundledplugins/softwareupdate.rst
index 48965a22..a4e1213e 100644
--- a/docs/bundledplugins/softwareupdate.rst
+++ b/docs/bundledplugins/softwareupdate.rst
@@ -65,6 +65,66 @@ More settings are available by :ref:`editing the correspondi.. _section in confi
 
 That restart commands for OctoPrint and the whole server can be configured under Settings > Server.
 
+.. _sec-bundledplugins-softwareupdate-cli:
+
+Command line usage
+------------------
+
+The functionality of the Software Update Plugin is also available on OctoPrint's command line interface under the
+``plugins`` sub command. It's is possible to check for updates via ``octoprint plugins softwareupdate:check``
+and to apply available updates via ``octoprint plugins softwareupdate:update``. Please the corresponding
+``--help`` pages on details:
+
+.. code-block:: none
+
+   $ octoprint plugins softwareupdate:check --help
+   Usage: octoprint plugins softwareupdate:check [OPTIONS] [TARGETS]...
+
+     Check for updates.
+
+     If any TARGETs are provided, only those components will be checked.
+
+     Examples:
+     - octoprint plugins softwareupdate:check
+         This will check all components for available updates,
+         utilizing cached version information.
+     - octoprint plugins softwareupdate:check --force
+         This will check all components for available updates,
+         ignoring any cached version information even if it's
+         still valid.
+     - octoprint plugins softwareupdate:check octoprint
+         This will only check OctoPrint itself for available
+         updates.
+
+   Options:
+     --force  Ignore the cache for the update check
+     --help   Show this message and exit.
+
+.. code-block:: none
+
+   $ octoprint plugins softwareupdate:update --help
+   Usage: octoprint plugins softwareupdate:update [OPTIONS] [TARGETS]...
+
+     Apply updates.
+
+     If any TARGETs are provided, only those components will be updated.
+
+     Examples:
+     - octoprint plugins softwareupdate:update
+         This will update all components with a pending update
+         that can be updated.
+     - octoprint plugins softwareupdate:update --force
+         This will force an update of all registered components
+         that can be updated, even if they don't have an updated
+         pending.
+     - octoprint plugins softwareupdate:update octoprint
+         This will only update OctoPrint and leave any further
+         components with pending updates at their current versions.
+
+   Options:
+     --force  Update even if already up to date
+     --help   Show this message and exit.
+
 .. _sec-bundledplugins-softwareupdate-configuration:
 
 Configuring the Plugin
diff --git a/src/octoprint/plugins/softwareupdate/cli.py b/src/octoprint/plugins/softwareupdate/cli.py
index 23ad08c7..36e44599 100644
--- a/src/octoprint/plugins/softwareupdate/cli.py
+++ b/src/octoprint/plugins/softwareupdate/cli.py
@@ -15,7 +15,24 @@ def commands(cli_group, pass_octoprint_ctx, *args, **kwargs):
 	@click.option("--force", is_flag=True, help="Ignore the cache for the update check")
 	@click.argument("targets", nargs=-1)
 	def check_command(force, targets):
-		"""Check for updates."""
+		"""
+		Check for updates.
+
+		If any TARGETs are provided, only those components will be checked.
+
+		\b
+		Examples:
+		- octoprint plugins softwareupdate:check
+		    This will check all components for available updates,
+		    utilizing cached version information.
+		- octoprint plugins softwareupdate:check --force
+		    This will check all components for available updates,
+		    ignoring any cached version information even if it's
+		    still valid.
+		- octoprint plugins softwareupdate:check octoprint
+		    This will only check OctoPrint itself for available
+		    updates.
+		"""
 		params = dict(force=force)
 		if targets:
 			params["check"] = ",".join(targets)
@@ -68,7 +85,24 @@ def commands(cli_group, pass_octoprint_ctx, *args, **kwargs):
 	@click.option("--force", is_flag=True, help="Update even if already up to date")
 	@click.argument("targets", nargs=-1)
 	def update_command(force, targets):
-		"""Apply updates."""
+		"""
+		Apply updates.
+
+		If any TARGETs are provided, only those components will be updated.
+
+		\b
+		Examples:
+		- octoprint plugins softwareupdate:update
+		    This will update all components with a pending update
+		    that can be updated.
+		- octoprint plugins softwareupdate:update --force
+		    This will force an update of all registered components
+		    that can be updated, even if they don't have an updated
+		    pending.
+		- octoprint plugins softwareupdate:update octoprint
+		    This will only update OctoPrint and leave any further
+		    components with pending updates at their current versions.
+		"""
 
 		data = dict(force=force)
 		if targets: