Document openstack-doc-tools and openstackdocstheme

Document openstack-doc-tools and openstackdocstheme

Problem description

Documentation for openstack-doc-tools and openstackdocstheme is currently divided between various README files in the project repositories and the OpenStack Documentation Contributor Guide. In some cases content is duplicated, outdated, or missing.

Proposed change

Create Sphinx documentation projects within the openstack-doc-tools and openstackdocstheme repositories, update and complete the documentation for both repositories, then publish the guides to

Add appropriate links to the new guides from the OpenStack Documentation Contributor Guide and the repository README files.

The openstack-doc-tools repository already has a Sphinx documentation project that is not currently published but that can be used as the basis for the guide.

openstackdocstheme also has a Sphinx documentation project that provides sample content for theme testing which should be retained or incorporated into the published guide.


  • Consolidate the content into a new OpenStack Documentation Tools Guide in the openstack-manuals repository.
  • Consolidate the content into the existing OpenStack Documentation Contributor Guide.
  • Maintain the status quo (do nothing).



Primary assignee:
  • Brian Moss (bmoss)
Other contributors:
  • Documentation team

Work Items

  • Create Sphinx documentation projects within the openstack-doc-tools and openstackdocstheme repositories.
  • Copy existing content into the new guides.
  • Add doc checks to the tox environment and Jenkins gate.
  • Publish the new guides to$REPO.
  • Replace content in original locations with links to the content in the new guides.
  • Edit content and add missing material.




Testing will follow the standard documentation review process.

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.