Document openstack-doc-tools and openstackdocstheme¶
https://blueprints.launchpad.net/openstack-doc-tools/+spec/document-tools
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 docs.openstack.org/developer/.
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.
Alternatives¶
- Consolidate the content into a new OpenStack Documentation Tools Guide
in the
openstack-manualsrepository. - Consolidate the content into the existing OpenStack Documentation Contributor Guide.
- Maintain the status quo (do nothing).
Implementation¶
Assignee(s)¶
- Primary assignee:
- Brian Moss (bmoss)
- Other contributors:
- Documentation team
Work Items¶
- Create Sphinx documentation projects within the
openstack-doc-toolsandopenstackdocsthemerepositories. - Copy existing content into the new guides.
- Add doc checks to the tox environment and Jenkins gate.
- Publish the new guides to docs.openstack.org/developer/$REPO.
- Replace content in original locations with links to the content in the new guides.
- Edit content and add missing material.
Dependencies¶
None
Testing¶
Testing will follow the standard documentation review process.
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.