openstack/openstack-manuals
Code Issues Proposed changes
openstack-manuals/doc/doc-contrib-guide/source/doc-tools/cli-reference.rst
Alexandra Settle 85107272be [contrib-guide] Updating url to doc-contrib-guide 
Based off conversation at the PTG, we agreed it would be
beneficial to ensure the contrib-guide is clearly marked
as the doc contrib guide outside of the title.

This change includes a redirect.

Change-Id: I5abf915f0b94a482afa961e6b86364c26aae5d79
2017-09-22 14:57:47 +00:00

3.7 KiB
Raw Blame History

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 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:

## 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:

  1. Clone the tools repository:

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

  2. Run the automated script:

    $ ./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.

  3. Verify that the file has built correctly.

  4. If you are satisfied with the generation, submit the change request for review:

    $ 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:

  1. Install openstack-doc-tools:

    $ pip install openstack-doc-tools

  2. С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.

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

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

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

  4. Generate CLI documentation using openstack-auto-commands:

    • To generate the CLI file, run:

      $ openstack-auto-commands CLIENT_NAME

    • To check a list of available options, run:

      $ openstack-auto-commands --help

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