From 1d1a0a8f570357cad753209556c9af806eeafdcb Mon Sep 17 00:00:00 2001 From: Peter Stachowski Date: Tue, 15 Mar 2016 21:56:16 +0000 Subject: [PATCH] Add 'generated files' section to contributor guide Instructions for regenerating CLI reference files was missing from the contributor guide. This has been added. A reference to the document location was added to the README.rst file. Change-Id: I4af156ebbd9ddc08c1c80c1ebad6d05203caba91 --- README.rst | 8 ++ .../source/tools-and-content-overview.rst | 118 +++++++++++++++++- 2 files changed, 125 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index a5255a5770..4b309d89fa 100644 --- a/README.rst +++ b/README.rst @@ -117,6 +117,14 @@ If you would like to contribute to the documents, please see the `OpenStack Documentation contributor guide `_. +Generated files +--------------- + +Some documentation files are generated using tools. These files include +a ``do not edit`` header and should not be modified by hand. Please see +`Generated files +`_. + Bugs ==== diff --git a/doc/contributor-guide/source/tools-and-content-overview.rst b/doc/contributor-guide/source/tools-and-content-overview.rst index 1dc3be4dec..d350c1b86a 100644 --- a/doc/contributor-guide/source/tools-and-content-overview.rst +++ b/doc/contributor-guide/source/tools-and-content-overview.rst @@ -68,7 +68,8 @@ information about Speciality Teams, including how to get involved, see: 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. + update the file using the :ref:`doc-tools` tool kit. Please see + `Generated files`_. .. list-table:: :header-rows: 1 @@ -136,11 +137,126 @@ 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/