History

Stephen Finucane bde286751d Include 'deprecation' as a flag There is support for displaying deprecation information in a somewhat structured manner (proper lists, emphasis on titles, etc.). However, the deprecation information is still included in the help text rather than in this flags section. This makes things more difficult than they need to be. Resolve this by instead including any deprecation information in the flags section. This will transform output from something like this: (String) DEPRECATED: Host to locate redis. Replaced by [DEFAULT]/transport_url to this: (String) Host to locate redis. Deprecated Replaced by [DEFAULT]/transport_url Which should be a little more obvious. Change-Id: Ifaee90a814fa3efee8b41eb0411535cff70e7309		2017-02-14 16:42:40 +00:00
..
templates	[config-ref] remove unnecessary template files	2016-11-11 16:08:13 +09:00
README.rst	[config-ref] Update README for RHEL/CentOS; diff_branches for Ocata	2016-11-30 19:47:02 +01:00
__init__.py	Rename autogenerate-config-docs to autogenerate_config_docs	2014-01-21 17:00:22 +01:00
autohelp-wrapper	Remove docbook	2016-11-22 10:20:20 +00:00
autohelp.py	Include 'deprecation' as a flag	2017-02-14 16:42:40 +00:00
diff_branches.py	[config-ref] Update README for RHEL/CentOS; diff_branches for Ocata	2016-11-30 19:47:02 +01:00
extract_swift_flags.py	[autohelp] config-ref-rst moves to config-reference	2015-12-20 20:56:08 +01:00
requirements.txt	Make diff_branches.py work again	2016-03-20 18:44:17 +01:00

README.rst

autogenerate_config_docs

Automatically generate configuration tables to document OpenStack.

Using the wrapper

autohelp-wrapper is the recommended tool to generate the configuration tables. Don't bother using 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).

Prior to running the following commands, 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

The workflow is:

$ pip install -rrequirements.txt
$ ./autohelp-wrapper update
$ $EDITOR sources/openstack-manuals/tools/autogenerate-config-flagmappings/*.flagmappings
$ ./autohelp-wrapper rst
$ # check the results in sources/openstack-manuals

This will generate the tables for all the known projects. Note for 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 flagmappings 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 doesn't 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 doesn't use a mapping file, but organize the tables using the various configuration files and sections. Most of the options must be described manually at the moment.

Generate 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