741b7e3ec0
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>
173 lines
5.4 KiB
ReStructuredText
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
|