Scripts overview

This section provides an overview of scripts used by the OpenStack documentation project, writers and developers, grouped by components they are part of.


openstackdocstheme is a theme and extension support for Sphinx documentation that is published to It provides an external link helper to automatically build links that change when branches are created for each release series.

For more information, see External Link Helper.


The oslo.config library provides two extensions, a configuration documentation directive and a configuration generator hook.

For more information, see Sphinx Integration for oslo.config and Sphinx Oslo Sample Config Generation.


The oslo.policy library provides two extensions, a policy documentation directive and a policy generator hook.

For more information, see Sphinx Oslo Sample Policy Generation.


The cliff framework provides a directive to document multiple commands.

For more information, see Sphinx Integration for cliff.


The stevedore library provides a single directive for listing plugins for an entrypoint.

For more information, see Sphinx Integration for stevedore.

openstack-doc-tools repository


Generates the sitemap.xml file.


Contains scripts for building documents in the openstack-manuals repository. Used inside the tox environments.

openstack-manuals repository

Several scripts currently reside in the openstack-manuals repository. It may be beneficial to consolidate these into the openstack-doc-tools repository.

Generates static, template-based HTML files for See Template generator details for more information.

Synchronizes the Glossary, common files, and some translations across multiple repositories, including api-site and security-doc.

Publishdocs job uses this script to publish documentation to


  • openstack-doc-tools must be released so it can be pinned in requirements files, enabling automation to work across repositories.

  • There are many undocumented synchronizations (automated and manual) between the various documentation repositories. These should be documented.

  • There are several jobs that must be run regularly, for example, updating the sitemap.xml file and the command line configuration reference. These should be documented.

  • Some manual jobs should be automated. For example, the sitemap.xml file should be automatically updated by the Gerritbot.