openstack/python-openstackclient
Code Issues Proposed changes

docs: Small cleanup of human interface guide

Browse Source 
Before we add more content.

Change-Id: I6cf28bdd217326db991466a21221b685124d4b99
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
This commit is contained in:
Stephen Finucane
2022-11-24 12:59:33 +00:00
parent 96162c24ea
commit abf1a7cc4b
1 changed files with 43 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
doc/source/contributor/humaninterfaceguide.rst
View File

@@ -117,14 +117,14 @@ interface to the user, not the user to the interface.
Commands should be discoverable via the interface itself. Commands should be discoverable via the interface itself.
To determine a list of available commands, use the :code:`-h` or To determine a list of available commands, use the ``-h`` or
:code:`--help` options: ``--help`` options:
.. code-block:: bash .. code-block:: bash
$ openstack --help $ openstack --help
For help with an individual command, use the :code:`help` command: For help with an individual command, use the ``help`` command:
.. code-block:: bash .. code-block:: bash
@@ -167,7 +167,7 @@ Command Structure
OpenStackClient has a consistent and predictable format for all of its commands. OpenStackClient has a consistent and predictable format for all of its commands.
* The top level command name is :code:`openstack` * The top level command name is ``openstack``
* Sub-commands take the form: * Sub-commands take the form:
.. code-block:: bash .. code-block:: bash
@@ -193,50 +193,56 @@ invocation regardless of action to be performed. They include authentication
credentials and API version selection. Most global options have a corresponding credentials and API version selection. Most global options have a corresponding
environment variable that may also be used to set the value. If both are present, environment variable that may also be used to set the value. If both are present,
the command-line option takes priority. The environment variable names are derived the command-line option takes priority. The environment variable names are derived
from the option name by dropping the leading dashes ('--'), converting each embedded from the option name by dropping the leading dashes (``--``), converting each embedded
dash ('-') to an underscore ('_'), and converting to upper case. dash (``-``) to an underscore (``_``), and converting to upper case.
* Global options shall always have a long option name, certain common options may * Global options shall always have a long option name, certain common options may
also have short names. Short names should be reserved for global options to limit also have short names. Short names should be reserved for global options to limit
the potential for duplication and multiple meanings between commands given the the potential for duplication and multiple meanings between commands given the
limited set of available short names. limited set of available short names.
* All long options names shall begin with two dashes ('--') and use a single dash
('-') internally between words (:code:`--like-this`). Underscores ('_') shall not * All long options names shall begin with two dashes (``--``) and use a single dash
(``-`` internally between words (``--like-this``). Underscores (``_``) shall not
be used in option names. be used in option names.
* Authentication options conform to the common CLI authentication guidelines in * Authentication options conform to the common CLI authentication guidelines in
:ref:`authentication`. :ref:`authentication`.
For example, :code:`--os-username` can be set from the environment via For example, ``--os-username`` can be set from the environment via
:code:`OS_USERNAME`. ``OS_USERNAME``.
--help ``--help``
++++++ ++++++++++
The standard :code:`--help` global option displays the documentation for invoking The standard ``--help`` global option displays the documentation for invoking
the program and a list of the available commands on standard output. All other the program and a list of the available commands on standard output. All other
options and commands are ignored when this is present. The traditional short options and commands are ignored when this is present. The traditional short
form help option (:code:`-h`) is also available. form help option (``-h``) is also available.
--version ``--version``
+++++++++ +++++++++++++
The standard :code:`--version` option displays the name and version on standard The standard ``--version`` option displays the name and version on standard
output. All other options and commands are ignored when this is present. output. All other options and commands are ignored when this is present.
Command Object(s) and Action Command Object(s) and Action
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Commands consist of an object described by one or more words followed by an action. Commands that require two objects have the primary object ahead of the action and the secondary object after the action. Any positional arguments identifying the objects shall appear in the same order as the objects. In badly formed English it is expressed as "(Take) object1 (and perform) action (using) object2 (to it)." Commands consist of an object described by one or more words followed by an
action. Commands that require two objects have the primary object ahead of the
action and the secondary object after the action. Any positional arguments
identifying the objects shall appear in the same order as the objects. In
badly formed English it is expressed as "(Take) object-1 (and perform) action
(using) object-2 (to it)."::
<object-1> <action> [<object-2>] <object-1> <action> [<object-2>]
Examples: Examples:
* :code:`group add user <group> <user>` * ``group add user <group> <user>``
* :code:`volume type list` # Note that :code:`volume type` is a two-word * ``volume type list`` (note that ``volume type`` is a two-word single object)
single object
The :code:`help` command is unique as it appears in front of a normal command The ``help`` command is unique as it appears in front of a normal command
and displays the help text for that command rather than execute it. and displays the help text for that command rather than execute it.
Object names are always specified in command in their singular form. This is Object names are always specified in command in their singular form. This is
@@ -256,21 +262,21 @@ meaning across multiple commands.
Option Forms Option Forms
++++++++++++ ++++++++++++
* **boolean**: boolean options shall use a form of :code:`--<true>|--<false>` * **boolean**: boolean options shall use a form of ``--<true>|--<false>``
(preferred) or :code:`--<option>|--no-<option>`. For example, the (preferred) or ``--<option>|--no-<option>``. For example, the
:code:`enabled` state of a project is set with :code:`--enable|--disable`. ``enabled`` state of a project is set with ``--enable|--disable``.
Command Output Command Output
-------------- --------------
The default command output is pretty-printed using the Python The default command output is pretty-printed using the Python
:code:`prettytable` module. ``prettytable`` module.
Machine-parsable output format may be specified with the :code:`--format` Machine-parsable output format may be specified with the ``--format``
option to :code:`list` and :code:`show` commands. :code:`list` commands option to ``list`` and ``show`` commands. ``list`` commands
have an option (:code:`--format csv`) for CSV output and :code:`show` commands have an option (``--format csv``) for CSV output and ``show`` commands
have an option (:code:`--format shell`) for the shell variable assignment have an option (``--format shell``) for the shell variable assignment
syntax of :code:`var="value"`. In both cases, all data fields are quoted with `"` syntax of ``var="value"``. In both cases, all data fields are quoted with ``"``
Help Commands Help Commands
------------- -------------
@@ -278,13 +284,13 @@ Help Commands
The help system is considered separately due to its special status The help system is considered separately due to its special status
among the commands. Rather than performing tasks against a system, it among the commands. Rather than performing tasks against a system, it
provides information about the commands available to perform those provides information about the commands available to perform those
tasks. The format of the :code:`help` command therefore varies from the tasks. The format of the ``help`` command therefore varies from the
form for other commands in that the :code:`help` command appears in front form for other commands in that the ``help`` command appears in front
of the first object in the command. of the first object in the command.
The options :code:`--help` and :code:`-h` display the global options and a The options ``--help`` and ``-h`` display the global options and a
list of the supported commands. Note that the commands shown depend on the API list of the supported commands. Note that the commands shown depend on the API
versions that are in effect; i.e. if :code:`--os-identity-api-version=3` is versions that are in effect; i.e. if ``--os-identity-api-version=3`` is
present Identity API v3 commands are shown. present Identity API v3 commands are shown.
Examples Examples
@@ -342,7 +348,7 @@ Using environment variables:
Machine Output Format Machine Output Format
--------------------- ---------------------
Using the csv output format with a list command: Using the CSV output format with a list command:
.. code-block:: bash .. code-block:: bash
@@ -351,7 +357,7 @@ Using the csv output format with a list command:
"ead97d84-6988-47fc-9637-3564fc36bc4b","appweb01","ACTIVE","10.4.128.13" "ead97d84-6988-47fc-9637-3564fc36bc4b","appweb01","ACTIVE","10.4.128.13"
Using the show command options of shell output format and adding a prefix of Using the show command options of shell output format and adding a prefix of
:code:`my_` to avoid collisions with existing environment variables: ``my_`` to avoid collisions with existing environment variables:
.. code-block:: bash .. code-block:: bash