Merge "Add spec for updating and publishing tools documentation"
This commit is contained in:
commit
c267b40ed5
|
@ -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