openstack/openstack-manuals
Code Issues Proposed changes

[contributor] reorganize documentation tools

Browse Source 
Reorganizes the Documentation tools section basing on
the principles of topic-based authoring.

Co-Authored-By: OlgaGusarenko <ogusarenko@mirantis.com>

Change-Id: I2f23828672dea091279ee53650275ed9ca48705b
Implements: blueprint contributor-guide-reorg
This commit is contained in:
KATO Tomoyuki 2016-07-09 20:35:14 +09:00
parent f5c1dd8b3e
commit 057cad023b
9 changed files with 307 additions and 449 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/contributor-guide/source/doc-tools.rst
View File

@ -1,23 +1,24 @@
.. _doc-tools:
===================
openstack-doc-tools
===================
=========================
Using documentation tools
=========================
The `openstack-doc-tools <https://github.com/openstack/openstack-doc-tools>`_
repository contains tools used by the OpenStack Documentation project.
The OpenStack documentation toolkit includes a number of scripts used
for performing automated tasks to maintain the OpenStack documentation
project. For example, there are tools that generate configuration and
command-line interface references, generate a sitemap, check niceness,
synchronize files used across multiple repositories, and others.
This chapter provides a general overview of the tools. Detailed documentation
is available at
https://github.com/openstack/openstack-doc-tools/tree/master/doc/source.
**Contents**
This section provides an overview of the documentation tools and their
location, explains how to install, configure, use, and contribute to them.
.. toctree::
:maxdepth: 2
doc-tools/scripts.rst
doc-tools/installation.rst
doc-tools/configuration.rst
doc-tools/contributing.rst
doc-tools/scripts.rst
doc-tools/cli-reference.rst
doc-tools/openstack-doc-test.rst
doc-tools/contributing.rst

122
doc/contributor-guide/source/doc-tools/cli-reference.rst Normal file
View File

@ -0,0 +1,122 @@
=========================================
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 <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 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``:
.. 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/cli-reference/source`` directory within
``openstack-manuals``:
.. code-block:: console
$ cd /path/to/openstack-manuals/doc/cli-reference/source
#. Generate CLI documentation using :command:`openstack-auto-commands`:
* To generate all CLI files, run:
.. code-block:: console
$ openstack-auto-commands --all
* To generate a specific 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>`.

60
doc/contributor-guide/source/doc-tools/configuration.rst
View File

@ -1,47 +1,47 @@
=============
Configuration
=============
=======================================
Configure OpenStack documentation tools
=======================================
If you run the ``openstack-doc-test --check-build``, it will copy all
the books to the directory ``publish-docs`` in the top-level directory
of your repository.
OpenStack documentation tools use the ``doc-test.conf`` file as a source for
the default settings.
By default, it outputs a directory with the same name as the directory
where the ``pom.xml`` file lives in, such as ``glossary``. You can
also check the output of the build job for the name.
By default, the :command:`openstack-doc-test --check-build` copies the books
to the ``publish-docs`` directory in the top-level directory of a project's
repository. You can modify the default settings for the books that require
special treatment by configuring the following options:
Some books need special treatment and there are three options you can
set in the file ``doc-test.conf``:
book
The name of a book that needs special treatment
* ``book`` - the name of a book that needs special treatment
* ``target_dir`` - the path of subdirectory starting at ``target``
that is the root for publishing
* ``publish_dir`` - a new name to publish a book under
target_dir
The path of subdirectory starting at ``target`` that is the root for
publishing
As an example, to publish the compute-api version 2 in the directory
``publish-docs/api/openstack-compute/2``, use::
book = openstack-compute-api-2
target_dir = target/docbkx/webhelp/api/openstack-compute/2
publish_dir = api/openstack-compute/2
These options can be specified multiple times and should
always be used this way. You do not need to set ``publish_dir`` but if
you set it, you need to use it every time.
publish_dir
A new name to publish a book under
.. note::
These are optional settings. The logic in the tool is
sufficient for many of the books.
You can specify these options multiple times and should always use them
this way.
* Source: http://git.openstack.org/cgit/openstack/openstack-doc-tools
* Bugs: http://bugs.launchpad.net/openstack-manuals
You do not need to set ``publish_dir`` but if you set it, you need to use
it every time.
As an example, to publish the compute-api version 2 to
``publish-docs/api/openstack-compute/2``, edit ``doc-test.conf`` as follows:
.. code-block:: none
book = openstack-compute-api-2
target_dir = target/docbkx/webhelp/api/openstack-compute/2
publish_dir = api/openstack-compute/2
Sample doc-test.conf file
~~~~~~~~~~~~~~~~~~~~~~~~~
.. code::
.. code-block:: none
[DEFAULT]

83
doc/contributor-guide/source/doc-tools/contributing.rst
View File

@ -1,50 +1,57 @@
============
Contributing
============
===========================================
Contribute to OpenStack documentation tools
===========================================
If you would like to contribute to the development of the
``openstack-doc-tools``, follow the steps in the `Developers Guide
<http://docs.openstack.org/infra/manual/developers.html>`_.
If you would like to contribute to OpenStack documentation tools, you are
welcome to submit a patch or file a bug against the toolkit.
Once those steps have been completed, changes to OpenStack
should be submitted for review via the Gerrit tool, following
the `gerrit workflow
<http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_
Contribute to the tool development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pull requests submitted through GitHub will be ignored.
To contribute to the development of ``openstack-doc-tools``, proceed with
the following steps:
Bugs should be filed on `Launchpad
<https://bugs.launchpad.net/openstack-manuals>`_, not GitHub.
#. Complete the procedures described
in the `Developers Guide <http://docs.openstack.org/infra/manual/developers.html>`_.
#. Follow `OpenStack Style Commandments <http://docs.openstack.org/developer/hacking/>`_
while developing improvements for the tool.
#. Run tests before you submit your change request.
For now, the documentation toolkit is tested with basic ``flake8``
and ``bashate`` tests. A test suite would be welcome.
Since the ``openstack-doc-test`` tool is used for gating of
the OpenStack documentation repositories, test building of
these repositories with any changes done within the tool repository:
#. Install ``openstack-doc-tools`` locally.
#. Check out the gated repositories.
The repositories gated by ``openstack-doc-tools`` are:
* api-site
* openstack-manuals
#. Run :command:`tox` inside of each gated repository.
#. Submit your change for review through the Gerrit tool as described
in the `gerrit workflow <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
.. warning::
Pull requests submitted through GitHub will be ignored.
.. note::
To be able to run ``"tox -e py27"`` successfully locally, add
``jinja2`` and ``markupsafe`` to your local ``test-requirements.txt``
file so the two get installed in your local virtual environment.
file to have them installed in your local virtual environment.
Style commandments
~~~~~~~~~~~~~~~~~~
File a bug against the tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Read the `OpenStack Style Commandments
<http://docs.openstack.org/developer/hacking/>`_.
Running tests
~~~~~~~~~~~~~
So far these tools are tested with only basic flake8 and bashate tests. A test
suite would be welcome!
Since the ``openstack-doc-test`` tool is used for gating of the OpenStack
documentation repositories, test building of these repositories with
any changes done here.
Testing can be done with simply a local install of
``openstack-doc-tools``, then checking out the gated repositories and
running: ``tox`` inside of each.
The repositories gated by ``openstack-doc-tools`` are:
* api-site
* openstack-manuals
If you experience an issue while using the ``openstack-doc-test`` tool,
file a bug on Launchpad in the `openstack-manuals project
<https://bugs.launchpad.net/openstack-manuals>`_, not on GitHub.

33
doc/contributor-guide/source/doc-tools/installation.rst
View File

@ -1,22 +1,29 @@
======================
Installation and usage
======================
.. _doc-toolsd-installation:
At the command line:
=====================================
Install OpenStack documentation tools
=====================================
.. code::
To install the documentation toolkit:
$ pip install openstack-doc-tools
#. Verify that you have installed
the `prerequisites <https://github.com/openstack/openstack-doc-tools/blob/master/README.rst>`_.
Or, if you have ``virtualenvwrapper`` installed:
#. Install the ``openstack-doc-tools`` package:
.. code::
.. code-block:: console
$ mkvirtualenv openstack-doc-tools
$ pip install openstack-doc-tools
$ pip install openstack-doc-tools
To use openstack-doc-tools in a project:
If you have ``virtualenvwrapper`` installed, run:
.. code::
.. code::
import os_doc_tools
$ mkvirtualenv openstack-doc-tools
$ pip install openstack-doc-tools
#. To use ``openstack-doc-tools``, import the tools to a project:
.. code-block:: console
import os_doc_tools

150
doc/contributor-guide/source/doc-tools/openstack-doc-test.rst
View File

@ -1,117 +1,89 @@
.. _openstack-doc-test:
==================
openstack-doc-test
==================
========================================
Validate OpenStack documentation content
========================================
OpenStack Validation tool
~~~~~~~~~~~~~~~~~~~~~~~~~
To test the validity of the OpenStack documentation content, use
the :command:`openstack-doc-test [options]` command with the following
available options:
SYNOPSIS
--------
.. note::
openstack-doc-test [options]
For option processing, the ``openstack-doc-test`` tool reads
the `doc-test.conf` in the top-level directory of the git repository.
DESCRIPTION
-----------
--api-site
Special handling for api-site and other API repositories
to handle WADL.
openstack-doc-test allows to test the validity of the OpenStack
documentation content.
--build-file-exception BUILD_FILE_EXCEPTION
File that will be skipped during delete and build checks to
generate dependencies. This should be done for invalid XML files only.
OPTIONS
-------
--check-build
Try to build books using modified files.
**General options**
--check-deletions
Check that deleted files are not used.
**--api-site**
Special handling for api-site and other API repositories
to handle WADL.
--check-links
Check that linked URLs are valid and reachable.
**--build-file-exception BUILD_FILE_EXCEPTION**
File that will be skipped during delete and build checks to
generate dependencies. This should be done for invalid XML files
only.
--check-niceness
Check the niceness of files, for example whitespace.
**--check-build**
Try to build books using modified files.
--check-syntax
Check the syntax of modified files.
**--check-deletions**
Check that deleted files are not used.
--check-all
Run all checks (default if no arguments are given).
**--check-links**
Check that linked URLs are valid and reachable.
--config-file PATH
Path to a config file to use. Multiple config files can be
specified, with values in later files taking precedence.
**--check-niceness**
Check the niceness of files, for example whitespace.
--debug
Enable debug code.
**--check-syntax**
Check the syntax of modified files.
--file-exception FILE_EXCEPTION
File that will be skipped during niceness and syntax validation.
**--check-all**
Run all checks (default if no arguments are given).
--force
Force the validation of all files and build all books.
**--config-file PATH**
Path to a config file to use. Multiple config files can be
specified, with values in later files taking precedence.
-h, --help
Show help message and exit.
**--debug**
Enable debug code.
--ignore-dir IGNORE_DIR
Directory to ignore for building of manuals. The parameter can
be passed multiple times to add several directories.
**--file-exception FILE_EXCEPTION**
File that will be skipped during niceness and syntax validation.
--language LANGUAGE, -l LANGUAGE
Build translated manual for language in path generate/$LANGUAGE .
**--force**
Force the validation of all files and build all books.
--only-book ONLY_BOOK
Build each specified manual.
**-h, --help**
Show help message and exit.
--parallel
Build books in parallel (default).
**--ignore-dir IGNORE_DIR**
Directory to ignore for building of manuals. The parameter can
be passed multiple times to add several directories.
--print-unused-files
Print list of files that are not included anywhere as part of
check-build.
**--language LANGUAGE, -l LANGUAGE**
Build translated manual for language in path generate/$LANGUAGE .
--publish
Setup content in publish-docs directory for publishing to
external website.
**--only-book ONLY_BOOK**
Build each specified manual.
--verbose
Verbose execution.
**--parallel**
Build books in parallel (default).
--version
Output version number.
**--print-unused-files**
Print list of files that are not included anywhere as part of
check-build.
Building of books generates the following output in the top-level directory
of the repository:
**--publish**
Setup content in publish-docs directory for publishing to
external website.
**--verbose**
Verbose execution.
**--version**
Output version number.
FILES
-----
Reads the file `doc-test.conf` in the top-level directory of the git
repository for option processing.
Building of books will generate in the top-level directory of the git
repository:
* a directory `publish-docs` with a copy of the build results.
* for each book build a log file named `build-${book}.log.gz`.
SEE ALSO
--------
* `OpenStack Documentation <http://wiki.openstack.org/wiki/Documentation>`_
Bugs
----
* openstack-doc-tools is hosted on Launchpad so you can view current
bugs at `openstack-manuals <https://bugs.launchpad.net/openstack-manuals/>`_
* The ``publish-docs`` directory with a copy of the build results.
* A log file for each book named ``build-${book}.log.gz``.

28
doc/contributor-guide/source/doc-tools/scripts.rst
View File

@ -1,22 +1,26 @@
=======
Scripts
=======
================
Scripts overview
================
This section provides an overview of scripts used by the OpenStack
documentation project grouped by repositories they are stored in.
openstack-doc-tools repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
autogenerate_config_docs
Generate configuration references published on
Generates configuration references published at
http://docs.openstack.org/mitaka/config-reference/.
build_environment directory (deprecated)
A Vagrant environment for working with the guides.
cleanup directory
Manually clean up documentation files.
Manually cleans up documentation files.
sitemap
Generate the sitemap.xml file.
Generates the ``sitemap.xml`` file.
bin
Contains scripts for building documents in the ``openstack-manuals``
@ -26,19 +30,19 @@ os_doc_tools directory
----------------------
openstack-doc-test
Check niceness of the documentation. Tests links, whitespace, line-endings.
Checks niceness of the documentation. Tests links, whitespace, line-endings.
See :ref:`openstack-doc-test`.
openstack-autohelp
Helper script run from the git repo by ``autogenerate_config_docs``.
A helper script run from the git repository by ``autogenerate_config_docs``.
openstack-auto-commands
Generate the command line reference published at
Generates the command-line interface reference published at
http://docs.openstack.org/cli-reference/. A helper script to use this
tool is available at ``bin/doc-tools-update-cli-reference``.
openstack-jsoncheck
Check JSON files. Used for the API guides
Checks JSON files. Used for the API guides.
openstack-manuals repository
@ -49,11 +53,11 @@ Several scripts currently reside in the `openstack-manuals
beneficial to consolidate these into the ``openstack-doc-tools`` repository.
www-generator.py
Generate static, template-based html files for http://docs.openstack.org/.
Generates static, template-based HTML files for http://docs.openstack.org/.
sync-projects.sh
Synchronizes the **Glossary**, common files, and some translations
across multiple repos, including ``api-site`` and ``security-doc``.
across multiple repositories, including ``api-site`` and ``security-doc``.
publishdocs.sh
Publishdocs job uses this script to publish documentation to

1
doc/contributor-guide/source/index.rst
View File

@ -30,7 +30,6 @@ Contents
ui-text-guidelines.rst
rst-conv.rst
json-conv.rst
tools-and-content-overview.rst
docs-builds.rst
build-locally.rst
doc-tools.rst

254
doc/contributor-guide/source/tools-and-content-overview.rst
View File

@ -1,254 +0,0 @@
.. _tools_and_content:
==========================
Tools and content overview
==========================
While in the past the documentation team used DocBook format, the guides are
now being converted from DocBook to ReStructured Text (RST). For more
information on the conversion, see `Doc Migration from DocBook to RST`_.
To work on the RST source files, find the :file:`/doc/guide/source/` directory
in a given OpenStack project. These files are built to
*docs.openstack.org/<guide-name>*, for example,
http://docs.openstack.org/user-guide.
Many cross-project manuals are in the
http://git.openstack.org/cgit/openstack/openstack-manuals/tree/ project.
To work on the DocBook and WADL source files for http://developer.openstack.org,
look for the http://git.openstack.org/cgit/openstack/api-site project
and use the same `development workflow`_.
The builds are listed on the :ref:`docs_builds` page, showing what
source files are built from.
OpenStack projects
~~~~~~~~~~~~~~~~~~
The OpenStack Documentation program focuses on documentation for the
following primary projects:
* Compute service (nova)
* Identity service (keystone)
* Image service (glance)
* Networking service (neutron)
* Block Storage service (cinder)
* Object Storage service (swift)
The Documentation program has cross-project liaisons (CPLs) who assist with
subject matter questions, reviews, doc bug triaging, and patching docs. Refer
to `documentation cross-project liaisons`_ for a list, and if you are
interested in becoming a CPL for docs, contact the Docs PTL.
These projects have two basic audiences: developers and sysadmins (think
operations or dev-ops). The RST-based documentation, because it automatically
generates doc from docstrings in the code, is much more for a developer
audience.
The developer documentation serves both Python developers who want to work on
OpenStack code and web developers who work with the OpenStack API.
What docs go where?
~~~~~~~~~~~~~~~~~~~
Refer to :ref:`content-specs` for a description of many documents. A long
listing of which repos house which documents is at :ref:`docs_builds`.
Generally this table describes the patterns for what goes where.
Specialty teams meet weekly to work on specific documents. For more
information about Speciality Teams, including how to get involved, see:
`Speciality Teams`_.
.. TODO (MZ) Change the link above as soon as the page is converted.
.. important::
Some content is completely generated using openstack-doc-tools,
such as the configuration option tables and the CLI reference information.
You will see the following warning in the source file: **<!-- This file is
automatically generated, do not edit -->**. When you see this, you can still
update the file using the :ref:`doc-tools` tool kit. Please see
`Generated files`_.
.. list-table::
:header-rows: 1
:widths: 10 20 20
:stub-columns: 0
:class: borderless
* - Wiki
- RST
- WADL/Swagger
* - Use for project docs.
- Use for nearly all guides (migrated to RST), for Python contributor
developer documentation, and quick starts.
- Use for API reference information built to developer.openstack.org/api-ref.html.
* - The audience is any project team member of OpenStack.
- The audience is Python developers who want to work on the project. For
the migrating content, it is for both end users and admin users.
- The audience is typically app developers consuming OpenStack services
through REST APIs.
* - Output is per-page at wiki.openstack.org.
- Output goes to *docs.openstack.org/<guide-name>* or
*docs.openstack.org/developer/<projectname>*.
- Output goes to developer.openstack.org/api-ref.html.
wiki.openstack.org (wikitext or RST)
------------------------------------
The OpenStack wiki contains project docs, legacy specs for blueprints, meeting
information, and meeting minutes. If there is a page you want to keep an eye
on, add it to your Watchlist (use :menuselection:`Actions > Watch` and see all
entries under :menuselection:`YourLogin > Watchlist` on the wiki).
If you add documentation specific pages, mark them as documentation-related
by adding ``[[Category:Documentation]]`` at the end of the page.
docs.openstack.org/developer/<projectname> (RST)
------------------------------------------------
The RST pages stored with the project code should be written with a developer
audience in mind, although you can find there is overlap in what an admin
needs to know and what a developer needs to know. High priorities for those
sites are wider coverage of doc strings, API doc, i18N methodology, and
architecture concepts that can help developers.
RST stands for ReStructured Text, a simple markup syntax that can be built
with Sphinx. Read more at `Sphinx documentation`_.
Maven plugin
------------
The Cloud Doc Tools Maven plug-in provides a build tool that Jenkins can use
to build PDF and HTML from DocBook and WADL source files. It is maintained at http://git.openstack.org/cgit/openstack/clouddocs-maven-plugin/tree/. We
track bugs against the output in the openstack-manuals Launchpad project.
The release notes are available in the Git repository.
Generated files
~~~~~~~~~~~~~~~
Some documentation files are automatically generated and these should
not be modified by hand. They contain a ``do not edit`` warning at
the beginning of the file and should only be generated using
the :ref:`doc-tools` tool kit.
CLI reference
-------------
The ``doc/cli-reference`` directory contains documentation for
the OpenStack command-line clients. See: `CLI-Reference`_.
Most of these files are generated using the ``openstack-auto-commands``
tool found in the ``openstack-doc-tools`` repository. See the repository
file ``os_doc_tools/resources/clients.yaml`` for a list of supported
clients. The generated files can be found in ``doc/cli-reference/source``.
.. important::
Some files are still manually maintained. If unsure, look for the
warning at the top of the file before attempting to re-generate it.
Automated generation
^^^^^^^^^^^^^^^^^^^^
Within the ``openstack-doc-tools`` repository, there is a script to
automate submission of an update to a client CLI documentation file.
The following instructions demonstrate how to use this script
using nova as an example client CLI.
Clone the tools repo.
.. code-block:: console
$ git clone git://git.openstack.org/openstack/openstack-doc-tools
$ cd openstack-doc-tools/bin
Run the automated script. This will generate a virtual environment.
This will install the necessary software and run the tool to re-generate
the file.
.. code-block:: console
$ ./doc-tools-update-cli-reference nova
The script will have cloned the ``openstack-manuals`` repo and created a
commit with the newly generated file. Check that the file looks correct
and if you are satisfied with it, submit it for review.
.. code-block:: console
$ cd openstack-manuals
$ git status
$ git show
$ 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.
Manual generation
^^^^^^^^^^^^^^^^^
Sometimes it may be necessary to re-generate these files manually.
To do this, you must have ``openstack-doc-tools`` installed.
.. code-block:: console
$ pip install openstack-doc-tools
To ensure that you have the latest tool changes, clone the repository.
This is also necessary if you make changes to the tool in order 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 .
$ popd
Change to the ``doc/cli-reference/source`` directory of your
``openstack-manuals`` clone and run the ``openstack-auto-commands``
command.
.. code-block:: console
$ cd /path/to/openstack-manuals/doc/cli-reference/source
$ openstack-auto-commands --all
To generate a specific 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,
submit them in a usual manner.
.. Links:
.. _`Doc Migration from DocBook to RST`: https://wiki.openstack.org/wiki/Documentation/Migrate
.. _`development workflow`: http://docs.openstack.org/infra/manual/developers.html#development-workflow
.. _`Speciality Teams`: https://wiki.openstack.org/wiki/Documentation/SpecialityTeams
.. _`Generated files`: http://docs.openstack.org/contributor-guide/tools-and-content-overview.html#Generated-files
.. _`documentation cross-project liaisons`: https://wiki.openstack.org/wiki/CrossProjectLiaisons#Documentation
.. _`Sphinx documentation`: http://sphinx-doc.org/rest.html
.. _`Transition Guide`: http://docbook.org/docs/howto/
.. _`CLI-Reference`: http://docs.openstack.org/cli-reference/