Document osc CLI

Change-Id: Idafe730021f272360ac0588f8b35e7d392c96d4b
Closes-Bug: #1735019

doc/source/cli/index.rst

@@ -0,0 +1,9 @@
+============
+Command List
+============
+
+.. toctree::
+   :glob:
+   :maxdepth: 3
+
+   *

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

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

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

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

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 = []

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
+This is a client for OpenStack Heat API. There's a Python API (the
-(the :mod:`heatclient` module), and a command-line script
+:mod:`heatclient` module), a `python-openstackclient`_ plugin for command-line
-(installed as :program:`heat`).
+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
+Code is mirrored `on GitHub`_. Submit bugs to the python-heatclient project on
-`Launchpad`_. Submit code to the openstack/python-heatclient project
+`Launchpad`_. Submit code to the openstack/python-heatclient project using
-using `Gerrit`_.
+`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

heatclient/osc/v1/stack.py

@@ -59,9 +59,9 @@ class CreateStack(command.ShowOne):
             action='append',
             help=_('Name of a resource to set a pre-create hook to. Resources '
                    'in nested stacks can be set using slash as a separator: '
-                   'nested_stack/another/my_resource. You can use wildcards '
+                   '``nested_stack/another/my_resource``. You can use '
-                   'to match multiple stacks or resources: '
+                   'wildcards to match multiple stacks or resources: '
-                   'nested_stack/an*/*_resource. This can be specified '
+                   '``nested_stack/an*/*_resource``. This can be specified '
                    'multiple times')
         )
         parser.add_argument(
@@ -210,9 +210,9 @@ class UpdateStack(command.ShowOne):
             '--pre-update', metavar='<resource>', action='append',
             help=_('Name of a resource to set a pre-update hook to. Resources '
                    'in nested stacks can be set using slash as a separator: '
-                   'nested_stack/another/my_resource. You can use wildcards '
+                   '``nested_stack/another/my_resource``. You can use '
-                   'to match multiple stacks or resources: '
+                   'wildcards to match multiple stacks or resources: '
-                   'nested_stack/an*/*_resource. This can be specified '
+                   '``nested_stack/an*/*_resource``. This can be specified '
                    'multiple times')
         )
         parser.add_argument(
@@ -1217,6 +1217,7 @@ class CancelStack(StackActionBase):
     """Cancel current task for a stack.
 
     Supported tasks for cancellation:
+
     * update
     * create
     """
@@ -1379,9 +1380,9 @@ class StackHookClear(command.Command):
             nargs='+',
             help=_('Resource names with hooks to clear. Resources '
                    'in nested stacks can be set using slash as a separator: '
-                   'nested_stack/another/my_resource. You can use wildcards '
+                   '``nested_stack/another/my_resource``. You can use '
-                   'to match multiple stacks or resources: '
+                   'wildcards to match multiple stacks or resources: '
-                   'nested_stack/an*/*_resource')
+                   '``nested_stack/an*/*_resource``')
         )
         return parser