Update the instructions to indicate which guides are no longer maintained by the docs team and how those docs are handled instead. Explain the data input to the www-generator.py tool Update the release instructions to explain how to update the templated portion of the site. Change-Id: I08bb228a6807bfcee0a6ab72ddaf229b455c9d1d Signed-off-by: Doug Hellmann <doug@doughellmann.com>
3.9 KiB
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:
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 withinopenstack-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<../quickstart/first-timers>
.