3.0 KiB
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-manuals
repository. - 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-tools
andopenstackdocstheme
repositories. - 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.