Document osc CLI
Closes-Bug:
ADD
doc/source/cli/index.rst
+============
+Command List
+============
+
+.. toctree::
+ :glob:
+ :maxdepth: 3
+
+ *

ADD
doc/source/cli/orchestration.rst
+=============
+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

ADD
doc/source/cli/software_config.rst
+===============
+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

ADD
doc/source/cli/software_deployment.rst
+===================
+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

ADD
doc/source/cli/stack.rst
+=====
+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

MODIFY
doc/source/conf.py
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 = []

MODIFY
doc/source/index.rst
doc/source/index.rst
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

MODIFY
heatclient/osc/v1/stack.py
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 '
- 'to match multiple stacks or resources: '
- 'nested_stack/an*/*_resource. This can be specified '
+ '``nested_stack/another/my_resource``. You can use '
+ 'wildcards to match multiple stacks or resources: '
+ '``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 '
- 'to match multiple stacks or resources: '
- 'nested_stack/an*/*_resource. This can be specified '
+ '``nested_stack/another/my_resource``. You can use '
+ 'wildcards to match multiple stacks or resources: '
+ '``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 '
- 'to match multiple stacks or resources: '
- 'nested_stack/an*/*_resource')
+ '``nested_stack/another/my_resource``. You can use '
+ 'wildcards to match multiple stacks or resources: '
+ '``nested_stack/an*/*_resource``')
)
return parser

Document osc CLI

Change-Id: Idafe730021f272360ac0588f8b35e7d392c96d4b
Closes-Bug: #1735019