openstack/openstack-doc-tools
Code Issues Proposed changes
e349adac5d
openstack-doc-tools/autogenerate-config-docs
History
Andreas Jaeger 086e22e466 Require hacking for additional checks 
Require hacking for additional pep8 checks to follow
OpenStack python hacking conventions.

Fix problems found by hacking.

Disable autogenerate-config-docs from check, it needs further
work to be clean enough.

Change-Id: Ib1dedf2e8262ba3d8ae1b58c4e4dbab82bbb5297
2014-01-03 11:25:56 +01:00
..
test Fix issues found by flake8 2013-12-18 21:23:12 +01:00
__init__.py Version handling 2014-01-01 17:33:55 +01:00
.gitignore Add Autogenerate-config-doc code to tools 2013-08-10 09:43:55 +08:00
autohelp.py Require hacking for additional checks 2014-01-03 11:25:56 +01:00
common.py Merge "Explicitely add license information to code files" 2013-12-30 16:44:40 +00:00
extract_swift_flags.py Require hacking for additional checks 2014-01-03 11:25:56 +01:00
flow.dia Add Autogenerate-config-doc code to tools 2013-08-10 09:43:55 +08:00
README.md Remove flagmappings 2013-12-16 21:54:06 +01:00

README.md

autogenerate-config-docs

Automatically generate configuration tables to document OpenStack.

Dependencies: python-git (at least version 0.3.2 RC1), oslo.config, openstack-doc-tools

Setting up your environment

Note: This tool is best run in a fresh VM environment, as running it requires installing the dependencies of the particular OpenStack product you are working with. Installing all of that on your normal machine could leave you with a bunch of cruft!

First install git and python-pip,

$ sudo apt-get install git python-pip

next, install oslo.config and GitPython

$ sudo pip install oslo.config "GitPython>=0.3.2.RC1"

then, checkout the repository you are working with:

$ git clone https://github.com/openstack/nova.git

(this guide makes reference to a /repos directory, so you should record the directory you are using and replace as appropriate below)

and the tool itself:

$ git clone https://github.com/openstack/openstack-doc-tools.git

and finally, the dependencies for the product you are working with:

$ sudo pip install -r nova/requirements.txt

Now you are ready to use the tool.

Using the tool

This tool is divided into three parts:

  1. Extraction of flags names eg

    $ openstack-doc-tools/autogenerate-config-docs/autohelp.py --action create -i nova.flagmappings -o names --path /repos/nova

  2. Grouping of flags

This is currently done manually, by using the flag name file and placing a category after a space.

eg

 $ head flagmappings/glance.flagmappings
 admin\_password registry
 admin\_role api
 admin\_tenant\_name registry
 admin\_user registry
 ...
  1. Creation of docbook-formatted configuration table files

eg

$ openstack-doc-tools/autogenerate-config-docs/autohelp.py --action create -i nova.flagmappings -o docbook --path /repos/nova

A worked example - updating the docs for H2

update automatically generated tables - from scratch

$ sudo apt-get update
$ sudo apt-get install git python-pip python-dev
$ sudo pip install git-review GitPython
$ git clone git://github.com/openstack/openstack-manuals.git
$ git clone git://github.com/openstack/openstack-doc-tools.git
$ cd openstack-manuals/
$ git review -d 35726
$ cd tools/autogenerate-config-flagmappings

Now, cloning and installing requirements for nova, glance, quantum

$ for i in nova glance quantum; do git clone git://github.com/openstack/$i.git; done
$ for i in nova glance quantum; do sudo pip install -r $i/requirements.txt; done

This missed some requirements for nova, which were fixed by:

$ sudo pip install python-glanceclient websockify pyasn1 python-cinderclient error_util
$ sudo apt-get install python-ldap python-lxml

Making the flag names update

../../openstack-doc-tools/autogenerate-config/autohelp.py -vvv --action update -i nova.flagmappings -o names --path ~/nova | more

At this point, seach through nova.flagmappings.new for anything labelled Unknown and fix, once that is done use:

../../openstack-doc-tools/autogenerate-config/autohelp.py -vvv --action create -i nova.flagmappings -o docbook --path ~/nova

to generate the XML files and move those into the appropriate part ofthe git repo