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>
5.4 KiB
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.
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
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:
## 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:
$ 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:
$ 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:
$ 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:
$ ./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:
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:
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:
$ ./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:
$ ./diff_branches.py stable/liberty stable/mitaka nova