=========================================
Generate Command-Line Interface Reference
=========================================

.. note::

   These instructions apply to the guides produced prior to the Pike
   release. The command line reference guides are now managed in the
   project repositories.

The OpenStack Command-Line Interface (CLI) Reference source files are stored
in the ``openstack-manuals`` repository. The majority of files are
automatically generated and should not be modified manually. To update
automatically generated files, use the ``openstack-auto-commands`` tool found
in the `openstack-doc-tools <https://git.openstack.org/cgit/openstack/openstack-doc-tools>`_
repository.

.. note::

   See ``os_doc_tools/resources/clients.yaml`` for a list of
   supported clients.

To distinguish an automatically generated file from the file that can be
edited manually, verify it contains the warning at the top of the file:

.. code-block:: none

   ## WARNING ######################################
   This file is automatically generated, do not edit
   #################################################


Update CLI documentation using an automated submission
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``openstack-doc-tools`` repository contains the script to automate
submission of an update to OpenStack clients CLI documentation.

To update CLI documentation and automatically submit a change request:

#. Clone the tools repository:

   .. code-block:: console

      $ git clone git://git.openstack.org/openstack/openstack-doc-tools
      $ cd openstack-doc-tools/bin

#. Run the automated script:

   .. code-block:: console

      $ ./doc-tools-update-cli-reference CLIENT_NAME

   The script generates a virtual environment, installs necessary software,
   generates the corresponding CLI documentation file based on the latest
   CLI client version, and commits the newly generated file locally.

#. Verify that the file has built correctly.
#. If you are satisfied with the generation, submit the change request for
   review:

   .. code-block:: console

      $ cd python-CLIENT_NAME
      $ git review

.. important::

   If inspection of the generated file reveals typographical errors
   or incorrect content, **do not fix these**. They must be fixed
   in the corresponding client repository (typically by adjusting
   the help strings for the various commands). Once the change
   has merged and a new client released, a new CLI documentation file
   can be generated with the updated content.


Update CLI documentation using a manual submission
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To re-generate CLI documentation and submit it manually:

#. Install ``openstack-doc-tools``:

   .. code-block:: console

      $ pip install openstack-doc-tools

#. Сlone the ``openstack-doc-tools`` repository to verify that you have
   the latest version of the tool. This is also required if you reconfigure
   the tool to generate a proper file.

   .. code-block:: console

      $ pushd <work_dir>
      $ git clone git://git.openstack.org/openstack/openstack-doc-tools
      $ cd openstack-doc-tools
      $ pip install .
      $ cd ..

#. Change to the ``doc/source/cli/`` directory within
   the CLI project. For example:

   .. code-block:: console

      $ cd /path/to/python-glanceclient/doc/source/cli/

#. Generate CLI documentation using :command:`openstack-auto-commands`:

   * To generate the CLI file, run:

     .. code-block:: console

        $ openstack-auto-commands CLIENT_NAME

   * To check a list of available options, run:

     .. code-block:: console

        $ openstack-auto-commands --help

#. Once you finish updating the generated files, commit the changes and
   :doc:`submit it on review in the usual manner<../quickstart/first-timers>`.