openstack-manuals/doc/contributor-guide/source/doc-tools/config-reference.rst
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

173 lines
5.4 KiB
ReStructuredText

================================
Generate Configuration Reference
================================
.. note::
These instructions apply to the guides produced prior to the Pike
release. The configuration reference guides are now managed in the
project repositories using `the Sphinx integration provided by
oslo.config
<https://docs.openstack.org/developer/oslo.config/sphinxext.html>`__.
The OpenStack Configuration 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 ``autohelp-wrapper`` tool found in the
`openstack-doc-tools <https://git.openstack.org/cgit/openstack/openstack-doc-tools>`_
repository.
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
#################################################
autogenerate_config_docs
~~~~~~~~~~~~~~~~~~~~~~~~
Automatically generate configuration tables to document OpenStack.
Requirements
------------
Prior to running the generation script, you need to install several
development packages.
On Ubuntu:
.. code-block:: console
$ sudo apt-get install python-dev python-pip python-virtualenv \
libxml2-dev libxslt1-dev zlib1g-dev \
libmysqlclient-dev libpq-dev libffi-dev \
libsqlite3-dev libldap2-dev libsasl2-dev \
libjpeg-dev liberasurecode-dev
On RHEL 7 and CentOS 7:
.. code-block:: console
$ sudo yum install https://www.rdoproject.org/repos/rdo-release.rpm
$ sudo yum update
$ sudo yum install python-devel python-pip python-virtualenv \
libxml2-devel libxslt-devel zlib-devel \
mariadb-devel postgresql-devel libffi-devel \
sqlite-devel openldap-devel cyrus-sasl-devel \
libjpeg-turbo-devel liberasurecode-devel gcc git
.. note::
* libjpeg is needed for ironic
* liberasurecode is needed for swift
Using the wrapper
-----------------
Use the ``autohelp-wrapper`` script to generate the configuration tables.
.. important::
Do not use ``autohelp.py`` manually.
The ``autohelp-wrapper`` script installs a virtual environment and all the
needed dependencies, clones or updates the projects and manuals repositories,
then runs the ``autohelp.py`` script in the virtual environment.
New and updated flagmappings are generated in the ``openstack-manuals``
repository (``tools/autogenerate-config-flagmappings/`` directory).
The workflow is:
.. code-block:: console
$ pip install -r requirements.txt
$ ./autohelp-wrapper update
$ $EDITOR sources/openstack-manuals/tools/autogenerate-config-flagmappings/*.flagmappings
$ ./autohelp-wrapper rst
Check the results in sources/openstack-manuals after completing the workflow.
This process generates the tables for all the known projects.
.. important::
For the Networking service (neutron) project, if the driver/plugin resides
outside the neutron repository, then the driver/plugin has to be explicitly
installed within the virtual environment to generate the configuration
options.
To generate the mappings and tables for a subset of projects, use the code
names as arguments:
.. code-block:: console
$ ./autohelp-wrapper update cinder heat
// edit the mappings files
$ ./autohelp-wrapper rst cinder heat
Flagmappings files
------------------
The tool uses flagmapping files to map options to custom categories. Flag
mapping files are in the ``tools/autogenerate-config-flagmappings`` folder of
the openstack-manuals project. Not all projects use flagmapping files. These
projects disabled by a ``$project.disable`` file in that folder. Flag mapping
files use the following format:
.. code-block:: ini
OPTION_SECTION/OPTION_NAME group1 [group2, ...]
Groups need to be defined manually to organize the configuration tables.
The group values can only contain alphanumeric characters, ``_`` and ``-``
(they will be used as document IDs).
To make the table titles more user friendly, create or edit the
``PROJECT.headers`` file in the manuals repository. Each line of this file
is of the form:
.. code-block:: none
GROUP A Nice Title
Working with branches
---------------------
``autohelp-wrapper`` works on the master branch by default, but you can tell it
to work on another branch:
.. code-block:: console
$ ./autohelp-wrapper -b stable/liberty update
.. note::
The ``-b`` switch does not apply to the ``openstack-manuals`` repository
which will be left untouched (no ``git branch``, no ``git update``).
Updating swift options
----------------------
Swift configuration tables are generated using the ``extract_swift_flags.py``
script. This script does not use a mapping file, but organizes the tables using
the various configuration files and sections. Most of the options must be
described manually at the moment.
Generating configuration difference
-----------------------------------
To generate "New, updated, and deprecated options" for each service,
run ``diff_branches.py``. For example:
.. code-block:: console
$ ./diff_branches.py stable/liberty stable/mitaka nova