openstack/openstack-doc-tools

History

Gauvain Pocentek 3d2f91cf8e autohelp: don't ignore cmd/ folders These folders used to bring command line options that we don't want to have in the generated tables, but the behavior has changed. This patch restores the import of files in the cmd/ folders, and handles special cases where the import is problematic. Change-Id: I0779e0f689d2f6f64149c3d111a8dd1ecd6cfc20 Partial-Bug: #1363954		2015-02-19 21:06:24 +01:00
..
test	Merge "Remove @author tags from copyright statements"	2014-10-09 05:24:38 +00:00
__init__.py	Rename autogenerate-config-docs to autogenerate_config_docs	2014-01-21 17:00:22 +01:00
autohelp-wrapper	Include ironic in the autohelp default projects	2015-01-21 19:15:29 +01:00
autohelp.py	autohelp: don't ignore cmd/ folders	2015-02-19 21:06:24 +01:00
diff_branches.py	Change config changes generator script	2014-12-12 16:12:33 +01:00
extract_swift_flags.py	autohelp: don't specify encoding in the base xml	2015-01-31 12:26:14 +01:00
flow.dia	Rename autogenerate-config-docs to autogenerate_config_docs	2014-01-21 17:00:22 +01:00
hooks.py	Add a hook for nova.cmd.spicehtml5proxy	2015-01-20 18:13:50 +01:00
README.rst	Update the autohelp readme	2014-08-26 08:25:07 +02:00
requirements.txt	Update the autohelp readme	2014-08-26 08:25:07 +02: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).

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.

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

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.