Scripts overview

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.


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.

os_doc_tools directory

Checks JSON files. Used for the API guides.

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 details.
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 a 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.
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.