Generate Command-Line Interface Reference

updated: 2017-06-18 09:19

Generate Command-Line Interface Reference
- Update CLI documentation using an automated submission
- Update CLI documentation using a manual submission

Generate Command-Line Interface Reference¶

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:

Clone the tools repository:

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

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.
Verify that the file has built correctly.
If you are satisfied with the generation, submit the change request for review:
```
$ cd openstack-manuals
$ 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:
```
$ 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.
```
$ pushd <work_dir>
$ git clone git://git.openstack.org/openstack/openstack-doc-tools
$ cd openstack-doc-tools
$ pip install .
$ cd ..
```
Change to the doc/cli-reference/source directory within openstack-manuals:
```
$ cd /path/to/openstack-manuals/doc/cli-reference/source
```
Generate CLI documentation using openstack-auto-commands:
- To generate all CLI files, run:
```
$ openstack-auto-commands --all
```
- To generate a specific CLI file, run:
```
$ openstack-auto-commands <CLIENT_NAME>
```
- To check a list of available options, run:
```
$ openstack-auto-commands --help
```
Once you finish updating the generated files, commit the changes and submit it on review in the usual manner.

updated: 2017-06-18 09:19

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.