From d1d4387babd7b249fc1fc3871a5756f88263c7e1 Mon Sep 17 00:00:00 2001 From: Zane Bitter Date: Wed, 29 Nov 2017 17:08:46 -0500 Subject: Document osc CLI Change-Id: Idafe730021f272360ac0588f8b35e7d392c96d4b Closes-Bug: #1735019 --- doc/source/cli/index.rst | 9 +++ doc/source/cli/orchestration.rst | 24 +++++++ doc/source/cli/software_config.rst | 16 +++++ doc/source/cli/software_deployment.rst | 22 ++++++ doc/source/cli/stack.rst | 123 +++++++++++++++++++++++++++++++++ doc/source/conf.py | 2 +- doc/source/index.rst | 43 +++++++++--- heatclient/osc/v1/stack.py | 19 ++--- 8 files changed, 238 insertions(+), 20 deletions(-) create mode 100644 doc/source/cli/index.rst create mode 100644 doc/source/cli/orchestration.rst create mode 100644 doc/source/cli/software_config.rst create mode 100644 doc/source/cli/software_deployment.rst create mode 100644 doc/source/cli/stack.rst 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 diff --git a/heatclient/osc/v1/stack.py b/heatclient/osc/v1/stack.py index 4a0c52e..3817bea 100644 --- a/heatclient/osc/v1/stack.py +++ b/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='', 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 -- cgit v1.2.1