101 lines
3.0 KiB
ReStructuredText
101 lines
3.0 KiB
ReStructuredText
..
|
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
|
License.
|
|
|
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
|
|
|
===================================================
|
|
Document openstack-doc-tools and openstackdocstheme
|
|
===================================================
|
|
|
|
https://blueprints.launchpad.net/openstack-doc-tools/+spec/document-tools
|
|
|
|
|
|
Problem description
|
|
===================
|
|
|
|
Documentation for `openstack-doc-tools
|
|
<http://git.openstack.org/cgit/openstack/openstack-doc-tools/>`_ and
|
|
`openstackdocstheme
|
|
<http://git.openstack.org/cgit/openstack/openstackdocstheme/>`_ is currently
|
|
divided between various README files in the project repositories and the
|
|
`OpenStack Documentation Contributor Guide
|
|
<https://docs.openstack.org/contributor-guide/index.html>`_. 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/
|
|
<https://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`` 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 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.
|
|
|
|
|
|
References
|
|
==========
|
|
|
|
- `openstack-doc-tools <http://git.openstack.org/cgit/openstack/openstack-doc-tools/>`_
|
|
- `openstackdocstheme <http://git.openstack.org/cgit/openstack/openstackdocstheme/>`_
|
|
- `openstack-manuals <http://git.openstack.org/cgit/openstack/openstack-manuals>`_
|
|
- `OpenStack Documentation Contributor Guide <https://docs.openstack.org/contributor-guide/index.html>`_
|