Skip to main content

Tools for OpenStack Documentation

Project description

This repository contains tools used by the OpenStack Documentation project.

For more details, see the OpenStack Documentation wiki page.

Prerequisites

Apache Maven must be installed to build the documentation.

To install Maven 3 for Ubuntu 12.04 and later, and Debian wheezy and later:

apt-get install maven

On Fedora:

yum install maven

You need to have Python 2.7 installed for using the tools.

This package needs a few external dependencies including lxml. If you do not have lxml installed, you can either install python-lxml or have it installed automatically and build from sources. To build lxml from sources, you need a C compiler and the xml and xslt development packages installed.

To install python-lxml, execute the following based on your distribution.

On Fedora:

yum install python-lxml

On openSUSE:

zypper in python-lxml

On Ubuntu:

apt-get install python-lxml

For building from source, install the dependencies of lxml.

On Fedora:

yum install python-devel libxml2-devel libxslt-devel

On openSUSE:

zypper in libxslt-devel

On Ubuntu:

apt-get install libxml2-dev libxslt-dev

Updating RNG schema files

The repository contains in the directory os_doc_tools/resources a local copy of some RNG schema files so that they do not need to be downloaded each time for validation of XML and WADL files.

Please see the README.txt in the directory for details on where these files come from.

Publishing of books

If you run the openstack-doc-test --check-build, it will copy all the books to the directory publish-docs in the top-level directory of your repository.

By default, it outputs a directory with the same name as the directory where the pom.xml file lives in, such as admin-guide-cloud. You can also check the output of the build job for the name.

Some books need special treatment and there are three options you can set in the file doc-test.conf:

  • book - the name of a book that needs special treatment

  • target_dir - the path of subdirectory starting at target that is the root for publishing

  • publish_dir - a new name to publish a book under

As an example, to publish the compute-api version 2 in the directory publish-docs/api/openstack-compute/2, use:

book = openstack-compute-api-2
target_dir = target/docbkx/webhelp/api/openstack-compute/2
publish_dir = api/openstack-compute/2

Note that these options can be specified multiple times and should always be used this way. You do not need to set publish_dir but if you set it, you need to use it every time.

Also note that these are optional settings, the logic in the tool is sufficient for many of the books.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openstack-doc-tools-0.32.0.tar.gz (171.0 kB view details)

Uploaded Source

Built Distribution

openstack_doc_tools-0.32.0-py2.py3-none-any.whl (180.2 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file openstack-doc-tools-0.32.0.tar.gz.

File metadata

File hashes

Hashes for openstack-doc-tools-0.32.0.tar.gz
Algorithm Hash digest
SHA256 bde467e6990d70afecc6577be7fd20743f5ef4de1f4faffec22959c975cec655
MD5 acb2d2d6f5cc8442482884d7b68754c1
BLAKE2b-256 f86f6e2833d1d244af37c593aec2d36e97696bb9be99204742056a5e1b3cb655

See more details on using hashes here.

Provenance

File details

Details for the file openstack_doc_tools-0.32.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for openstack_doc_tools-0.32.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 ec6d9beaa07f41de9e7611e547f9110bff254f46b118ab91bc2693b7f243c3b9
MD5 170afd9eb9361c62d30b7818c12df7df
BLAKE2b-256 0e18d4cb7ded00503b4b6138bce959c8cc39750b1310844393b83d55577408eb

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page