openstack/openstack-manuals
Code Issues Proposed changes

Merge "Add 'generated files' section to contributor guide"

Browse Source
This commit is contained in:
Jenkins 2016-04-13 13:51:03 +00:00 committed by Gerrit Code Review
commit 6e40770c88
2 changed files with 125 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.rst
View File

@ -116,6 +116,14 @@ If you would like to contribute to the documents, please see the
`OpenStack Documentation contributor guide
<http://docs.openstack.org/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
<http://docs.openstack.org/contributor-guide/tools-and-content-overview.html#Generated-files/>`_.
Bugs
====

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

@ -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: **<!-- 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.
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 <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/