Doug Hellmann 741b7e3ec0 update contributor guide based on changes after migration project
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>
2017-07-03 14:28:59 +00:00

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

  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/cli-reference/source directory within openstack-manuals:

    $ cd /path/to/openstack-manuals/doc/cli-reference/source
  4. 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
  5. Once you finish updating the generated files, commit the changes and submit it on review in the usual manner<../quickstart/first-timers>.