diff --git a/doc/contributor-guide/source/doc-tools.rst b/doc/contributor-guide/source/doc-tools.rst index bd28e2ff68..94a102b384 100644 --- a/doc/contributor-guide/source/doc-tools.rst +++ b/doc/contributor-guide/source/doc-tools.rst @@ -1,23 +1,24 @@ .. _doc-tools: -=================== -openstack-doc-tools -=================== +========================= +Using documentation tools +========================= -The `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 diff --git a/doc/contributor-guide/source/doc-tools/cli-reference.rst b/doc/contributor-guide/source/doc-tools/cli-reference.rst new file mode 100644 index 0000000000..6102362e07 --- /dev/null +++ b/doc/contributor-guide/source/doc-tools/cli-reference.rst @@ -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 `_ +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 + + 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 + $ 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 + + * 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>`. diff --git a/doc/contributor-guide/source/doc-tools/configuration.rst b/doc/contributor-guide/source/doc-tools/configuration.rst index 7c807851d7..902ccaab35 100644 --- a/doc/contributor-guide/source/doc-tools/configuration.rst +++ b/doc/contributor-guide/source/doc-tools/configuration.rst @@ -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] diff --git a/doc/contributor-guide/source/doc-tools/contributing.rst b/doc/contributor-guide/source/doc-tools/contributing.rst index 8e01b7f39c..3eeef97a5c 100644 --- a/doc/contributor-guide/source/doc-tools/contributing.rst +++ b/doc/contributor-guide/source/doc-tools/contributing.rst @@ -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 -`_. +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 -`_ +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 -`_, not GitHub. +#. Complete the procedures described + in the `Developers Guide `_. + +#. Follow `OpenStack Style Commandments `_ + 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 `_. + + .. 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 -`_. - - -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 +`_, not on GitHub. diff --git a/doc/contributor-guide/source/doc-tools/installation.rst b/doc/contributor-guide/source/doc-tools/installation.rst index 3993ab6732..aa975f2704 100644 --- a/doc/contributor-guide/source/doc-tools/installation.rst +++ b/doc/contributor-guide/source/doc-tools/installation.rst @@ -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 `_. -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 diff --git a/doc/contributor-guide/source/doc-tools/openstack-doc-test.rst b/doc/contributor-guide/source/doc-tools/openstack-doc-test.rst index e852f801e7..ad13f0b82c 100644 --- a/doc/contributor-guide/source/doc-tools/openstack-doc-test.rst +++ b/doc/contributor-guide/source/doc-tools/openstack-doc-test.rst @@ -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 `_ - -Bugs ----- - -* openstack-doc-tools is hosted on Launchpad so you can view current - bugs at `openstack-manuals `_ +* The ``publish-docs`` directory with a copy of the build results. +* A log file for each book named ``build-${book}.log.gz``. diff --git a/doc/contributor-guide/source/doc-tools/scripts.rst b/doc/contributor-guide/source/doc-tools/scripts.rst index 3f19751b16..affd01f6e1 100644 --- a/doc/contributor-guide/source/doc-tools/scripts.rst +++ b/doc/contributor-guide/source/doc-tools/scripts.rst @@ -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 diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index ae36514437..8017c394bd 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -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 diff --git a/doc/contributor-guide/source/tools-and-content-overview.rst b/doc/contributor-guide/source/tools-and-content-overview.rst deleted file mode 100644 index ad8cc4c927..0000000000 --- a/doc/contributor-guide/source/tools-and-content-overview.rst +++ /dev/null @@ -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/*, 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: ****. 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/* or - *docs.openstack.org/developer/*. - - 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/ (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 - $ 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 - -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/