From e4a7942e0341511163c8baeff01f94492b822cd0 Mon Sep 17 00:00:00 2001
From: Brian Moss <kallimachos@gmail.com>
Date: Fri, 7 Apr 2017 14:32:33 +1000
Subject: [PATCH] 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
---
 specs/pike/document-tools.rst | 100 ++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 specs/pike/document-tools.rst

diff --git a/specs/pike/document-tools.rst b/specs/pike/document-tools.rst
new file mode 100644
index 0000000..a2d1af1
--- /dev/null
+++ b/specs/pike/document-tools.rst
@@ -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>`_