Tools used by OpenStack Documentation
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Gauvain Pocentek 52537d2341 switch to jinja templates 6 years ago
extra_repos Repo change for networking-bagpipe-l2 6 years ago
releasenotes/notes switch to jinja templates 6 years ago
requirements Repo change for networking-bagpipe-l2 6 years ago
templates switch to jinja templates 6 years ago
test Drop use of 'oslo' namespace package 7 years ago
README.rst [autohelp] document required development packages 6 years ago Rename autogenerate-config-docs to autogenerate_config_docs 8 years ago
autohelp-wrapper autohelp: keep the projects names sorted 6 years ago switch to jinja templates 6 years ago diff_branches: add RST support 6 years ago extract_swift_flags: add RST support 6 years ago
flow.dia Rename autogenerate-config-docs to autogenerate_config_docs 8 years ago Fix alphabetical order in 6 years ago
requirements.txt diff_branches: use jinja templates to create the files 6 years ago



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 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 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. For Ubuntu install the required packages with the following command:

$ sudo apt-get install python-dev libxml2-dev libxslt1-dev libz-dev \
                       libmysqlclient-dev libpq-dev libffi-dev \
                       libsqlite3-dev libldap2-dev libsasl2-dev

The workflow is:

$ pip install -rrequirements.txt
$ ./autohelp-wrapper update
$ $EDITOR sources/openstack-manuals/tools/autogenerate-config-flagmappings/*.flagmappings
$ ./autohelp-wrapper docbook
$ # 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 in stackforge, 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 docbook cinder heat

Creating mappings for a new project

Run the wrapper with the create subcommand:

$ ./autohelp-wrapper create zaqar

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 docbook 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 update -b stable/icehouse


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 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.