Add spec for updating and publishing tools documentation
Update and complete the documentation for openstack-doc-tools and openstackdocstheme, and publish guides to docs.openstack.org/developer. Change-Id: I8437d28079a4da544cf6085704cccff7a7587f23
This commit is contained in:
parent
661dd09963
commit
e4a7942e03
|
@ -0,0 +1,100 @@
|
||||||
|
..
|
||||||
|
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>`_
|
Loading…
Reference in New Issue