Document osc CLI

Change-Id: Idafe730021f272360ac0588f8b35e7d392c96d4b
Closes-Bug: #1735019

7 files changed, 228 insertions, 11 deletions

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 0000000..d58a320
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,9 @@
+============
+Command List
+============
+
+.. toctree::
+   :glob:
+   :maxdepth: 3
+
+   *
diff --git a/doc/source/cli/orchestration.rst b/doc/source/cli/orchestration.rst
new file mode 100644
index 0000000..1c20e4c
--- /dev/null
+++ b/doc/source/cli/orchestration.rst
@@ -0,0 +1,24 @@
+=============
+orchestration
+=============
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: orchestration template validate
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: orchestration template version list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: orchestration template function list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: orchestration resource_type list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: orchestration resource_type show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: orchestration build info
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: orchestration service list
diff --git a/doc/source/cli/software_config.rst b/doc/source/cli/software_config.rst
new file mode 100644
index 0000000..b754308
--- /dev/null
+++ b/doc/source/cli/software_config.rst
@@ -0,0 +1,16 @@
+===============
+software config
+===============
+
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software config list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software config create
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software config show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software config delete
diff --git a/doc/source/cli/software_deployment.rst b/doc/source/cli/software_deployment.rst
new file mode 100644
index 0000000..b8ccbe1
--- /dev/null
+++ b/doc/source/cli/software_deployment.rst
@@ -0,0 +1,22 @@
+===================
+software deployment
+===================
+
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software deployment list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software deployment create
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software deployment show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software deployment output show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software deployment delete
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: software deployment metadata show
diff --git a/doc/source/cli/stack.rst b/doc/source/cli/stack.rst
new file mode 100644
index 0000000..175867e
--- /dev/null
+++ b/doc/source/cli/stack.rst
@@ -0,0 +1,123 @@
+=====
+stack
+=====
+
+Basic actions
+-------------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack create
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack update
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack cancel
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack delete
+
+Outputs
+-------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack output list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack output show
+
+Resources
+---------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack resource list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack resource show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack resource metadata
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack resource mark unhealthy
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack resource signal
+
+Events
+------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack event list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack event show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack failures list
+
+Input data
+----------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack template show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack environment show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack file list
+
+User hooks
+----------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack hook poll
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack hook clear
+
+Other actions
+-------------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack check
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack suspend
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack resume
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack export
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack abandon
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack adopt
+
+Snapshots
+---------
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack snapshot list
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack snapshot create
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack snapshot restore
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack snapshot show
+
+.. autoprogram-cliff:: openstack.orchestration.v1
+   :command: stack snapshot delete
diff --git a/doc/source/conf.py b/doc/source/conf.py
index e208359..78a716f 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -36,7 +36,7 @@ exec(open(os.path.join("ext", "gen_ref.py")).read())
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'openstackdocstheme']
+extensions = ['sphinx.ext.autodoc', 'openstackdocstheme', 'cliff.sphinxext']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0080645..bf9ec8a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,10 +1,11 @@
 Python bindings to the OpenStack Heat API
 =========================================
 
-This is a client for OpenStack Heat API. There's a Python API
-(the :mod:`heatclient` module), and a command-line script
-(installed as :program:`heat`).
+This is a client for OpenStack Heat API. There's a Python API (the
+:mod:`heatclient` module), a `python-openstackclient`_ plugin for command-line
+use, and a legacy command-line script (installed as :program:`heat`).
 
+==========
 Python API
 ==========
 
@@ -52,8 +53,28 @@ Reference
     ref/index
     ref/v1/index
 
-Command-line Tool
-=================
+============================
+OpenStackClient Command Line
+============================
+
+The preferred way of accessing Heat via the command line is using the
+python-heatclient's plugin for `python-openstackclient`_. Heat commands are
+available through the ``openstack`` CLI command when both python-heatclient and
+python-openstackclient are installed.
+
+.. toctree::
+    :maxdepth: 2
+
+    cli/index
+
+.. _python-openstackclient: https://docs.openstack.org/python-openstackclient
+
+========================
+Legacy Command-line Tool
+========================
+
+The ``heat`` command is provided as a legacy CLI option. Users should prefer
+using the python-openstackclient plugin via the ``openstack`` command instead.
 
 In order to use the CLI, you must provide your OpenStack username,
 password, tenant, and auth endpoint. Use the corresponding
@@ -79,20 +100,22 @@ Once you've configured your authentication parameters, you can run
 ``heat help`` to see a complete listing of available commands.
 
 Man Pages
-=========
+---------
 
 .. toctree::
     :maxdepth: 1
 
     man/heat
 
+
+============
 Contributing
 ============
 
-Code is hosted `on GitHub`_. Submit bugs to the Heat project on
-`Launchpad`_. Submit code to the openstack/python-heatclient project
-using `Gerrit`_.
+Code is mirrored `on GitHub`_. Submit bugs to the python-heatclient project on
+`Launchpad`_. Submit code to the openstack/python-heatclient project using
+`Gerrit`_.
 
 .. _on GitHub: https://github.com/openstack/python-heatclient
 .. _Launchpad: https://launchpad.net/python-heatclient
-.. _Gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow
+.. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow