Refactor Charm Guide

Refactor the charm guide to have a Diataxis framework alignment. This
organizes the set of documentation into a variety of categories such as
getting started, how-tos, concepts, and reference material.

Change-Id: I7981ff6ac4b543020bfa78f352843370fcf09173

doc/source/_extra/.htaccess

@@ -0,0 +1,47 @@
+redirectmatch 301 /charm-guide/latest/find-us.html$	/charm-guide/latest/community.html
+redirectmatch 301 /charm-guide/latest/charm-anatomy.html$	/charm-guide/latest/concepts/charm-anatomy.html
+redirectmatch 301 /charm-guide/latest/charms-and-bundles.html$	/charm-guide/latest/getting-started/charms-and-bundles.html
+redirectmatch 301 /charm-guide/latest/getting-started.html$	/charm-guide/latest/getting-started/index.html
+redirectmatch 301 /charm-guide/latest/new-api-charm.html$	/charm-guide/latest/howto/new-api-charm.html
+redirectmatch 301 /charm-guide/latest/new-manila-charm.html$	/charm-guide/latest/howto/new-manila-charm.html
+redirectmatch 301 /charm-guide/latest/new-sdn-charm.html$	/charm-guide/latest/howto/new-sdn-charm.html
+redirectmatch 301 /charm-guide/latest/backport-policy.html$	/charm-guide/latest/reference/backport-policy.html
+redirectmatch 301 /charm-guide/latest/coding-guidelines.html$	/charm-guide/latest/reference/coding-guidelines.html
+redirectmatch 301 /charm-guide/latest/creating-charms.html$	/charm-guide/latest/reference/creating-charms.html
+redirectmatch 301 /charm-guide/latest/feature-specification.html$	/charm-guide/latest/reference/feature-specification.html
+redirectmatch 301 /charm-guide/latest/how-to-contribute.html$	/charm-guide/latest/reference/how-to-contribute.html
+redirectmatch 301 /charm-guide/latest/making-a-change.html$	/charm-guide/latest/reference/making-a-change.html
+redirectmatch 301 /charm-guide/latest/openstack-charms.html$	/charm-guide/latest/reference/openstack-charms.html
+redirectmatch 301 /charm-guide/latest/author-guides/reactive-handlers-optimization.html$	/charm-guide/latest/reference/reactive-handlers-optimization.html
+redirectmatch 301 /charm-guide/latest/release-policy.html$	/charm-guide/latest/reference/release-policy.html
+redirectmatch 301 /charm-guide/latest/release-schedule.html$	/charm-guide/latest/reference/release-schedule.html
+redirectmatch 301 /charm-guide/latest/release-timeline-2008.html$	/charm-guide/latest/reference/release-timeline-2008.html
+redirectmatch 301 /charm-guide/latest/release-timeline-2010.html$	/charm-guide/latest/reference/release-timeline-2010.html
+redirectmatch 301 /charm-guide/latest/release-timeline-2101.html$	/charm-guide/latest/reference/release-timeline-2101.html
+redirectmatch 301 /charm-guide/latest/release-timeline-2104.html$	/charm-guide/latest/reference/release-timeline-2104.html
+redirectmatch 301 /charm-guide/latest/release-timeline-2110.html$	/charm-guide/latest/reference/release-timeline-2110.html
+redirectmatch 301 /charm-guide/latest/rotas.html$	/charm-guide/latest/reference/rotas.html
+redirectmatch 301 /charm-guide/latest/support-notes.html$	/charm-guide/latest/reference/support-notes.html
+redirectmatch 301 /charm-guide/latest/testing.html$	/charm-guide/latest/reference/testing.html
+redirectmatch 301 /charm-guide/latest/1610.html$	/charm-guide/latest/release-notes/1610.html
+redirectmatch 301 /charm-guide/latest/1702.html$	/charm-guide/latest/release-notes/1702.html
+redirectmatch 301 /charm-guide/latest/1708.html$	/charm-guide/latest/release-notes/1708.html
+redirectmatch 301 /charm-guide/latest/1711.html$	/charm-guide/latest/release-notes/1711.html
+redirectmatch 301 /charm-guide/latest/1802.html$	/charm-guide/latest/release-notes/1802.html
+redirectmatch 301 /charm-guide/latest/1805.html$	/charm-guide/latest/release-notes/1805.html
+redirectmatch 301 /charm-guide/latest/1808.html$	/charm-guide/latest/release-notes/1808.html
+redirectmatch 301 /charm-guide/latest/1811.html$	/charm-guide/latest/release-notes/1811.html
+redirectmatch 301 /charm-guide/latest/1904.html$	/charm-guide/latest/release-notes/1904.html
+redirectmatch 301 /charm-guide/latest/1907.html$	/charm-guide/latest/release-notes/1907.html
+redirectmatch 301 /charm-guide/latest/1910.html$	/charm-guide/latest/release-notes/1910.html
+redirectmatch 301 /charm-guide/latest/2002.html$	/charm-guide/latest/release-notes/2002.html
+redirectmatch 301 /charm-guide/latest/2005.html$	/charm-guide/latest/release-notes/2005.html
+redirectmatch 301 /charm-guide/latest/2008.html$	/charm-guide/latest/release-notes/2008.html
+redirectmatch 301 /charm-guide/latest/2010.html$	/charm-guide/latest/release-notes/2010.html
+redirectmatch 301 /charm-guide/latest/2101.html$	/charm-guide/latest/release-notes/2101.html
+redirectmatch 301 /charm-guide/latest/2103_Trilio.html$	/charm-guide/latest/release-notes/2103_Trilio.html
+redirectmatch 301 /charm-guide/latest/2104.html$	/charm-guide/latest/release-notes/2104.html
+redirectmatch 301 /charm-guide/latest/2106_Trilio.html$	/charm-guide/latest/release-notes/2106_Trilio.html
+redirectmatch 301 /charm-guide/latest/2110.html$	/charm-guide/latest/release-notes/2110.html
+redirectmatch 301 /charm-guide/latest/release-notes.html$	/charm-guide/latest/release-notes/index.html
+redirectmatch 301 /charm-guide/latest/release-notes-template.html$	/charm-guide/latest/release-notes/release-notes-template.html

doc/source/author-guides/index.rst

@@ -1,16 +0,0 @@
-.. _author-notes-index:
-
-============================
-OpenStack Charm Author Notes
-============================
-
-These notes are charm development topics that charm authors may encounter
-whilst writing or modifying charms. These are based around using
-``charms.reactive`` and ``charms.openstack`` to write *reactive* charms.  These
-have some potential pitfalls that these notes address.
-
-.. toctree::
-   :maxdepth: 1
-   :includehidden:
-
-   reactive-handlers-optimization

doc/source/community.rst

@@ -1,6 +1,6 @@
-==========
-Talk to us
-==========
+=========
+Community
+=========
 
 We'd love to hear from you!
 

doc/source/concepts/index.rst

@@ -0,0 +1,8 @@
+########
+Concepts
+########
+
+.. toctree::
+   :maxdepth: 1
+
+   charm-anatomy

doc/source/conf.py

@@ -48,7 +48,7 @@ source_suffix = '.rst'
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'contents'
 
 # General information about the project.
 copyright = u'2016, OpenStack contributors'
@@ -83,7 +83,7 @@ release = ''
 
 exclude_patterns = [
      "_build",
-     "release-notes-template.rst"
+     "release-notes/release-notes-template.rst"
 ]
 
 # The reST default role (used for this markup: `text`) to use for all

doc/source/contents.rst

@@ -0,0 +1,26 @@
+########
+Contents
+########
+
+.. toctree::
+   :maxdepth: 1
+
+   Home <index>
+   Getting started <getting-started/index>
+   How-to guides <howto/index>
+   Concepts <concepts/index>
+   Reference <reference/index>
+
+   Release notes <release-notes/index>
+   Release schedule <reference/release-schedule>
+
+   Community <community>
+
+
+Search
+======
+
+* :ref:`Charm Guide search <search>`: Search the contents of this
+  document.
+* `OpenStack wide search <https://docs.openstack.org>`_: Search the wider set
+  of OpenStack documentation, including forums.

doc/source/getting-started/charms-and-bundles.rst

@@ -21,7 +21,7 @@ Ubuntu releases. The currently supported combinations of OpenStack and Ubuntu
 are listed on the `Ubuntu Cloud Archive`_ wiki page.
 
 The full list of supported charms is given on the :doc:`Charms
-<openstack-charms>` page in this guide.
+</reference/openstack-charms>` page in this guide.
 
 Charm Store namespaces
 ----------------------

doc/source/howto/index.rst

@@ -0,0 +1,18 @@
+#######
+How-to
+#######
+
+Operators
+---------
+
+`Coming soon`
+
+Contributors
+------------
+
+.. toctree::
+   :maxdepth: 1
+
+   new-sdn-charm
+   new-api-charm
+   new-manila-charm

doc/source/index.rst

@@ -1,30 +1,66 @@
-=====================
-OpenStack Charm Guide
-=====================
+================
+OpenStack Charms
+================
 
-Charmed OpenStack is an enterprise grade OpenStack distribution that leverages
-MAAS, Juju, and the `OpenStack Charms`_ to simplify the deployment and
-management of an OpenStack cloud.
+OpenStack Charms are a collection of Charmed Operators used to deploy and manage
+enterprise grade OpenStack clouds using `MAAS`_ and `Juju`_, simplifying the
+deployment and operations of OpenStack.
 
-The OpenStack Charm Guide is the main source of information for the development
-of the OpenStack Charms. Release notes and support notes are also to be
-found here.
+Charmed Operators, also called `charms`, contain specific knowledge for
+deployment and lifecycle management of applications and services. As such,
+you will find the OpenStack charms collection consists of a charm per OpenStack
+service as well as key services critical to a production grade OpenStack cloud,
+such as RabbitMQ and MySQL.
+
+Getting started
+---------------
+
+Learn how to deploy an OpenStack cloud using OpenStack Charmed Operators, Juju
+and MAAS. Those new to using OpenStack Charmed Operators should start here.
 
 .. toctree::
-   :maxdepth: 2
-   :includehidden:
+   :maxdepth: 1
+
+   getting-started/index
+
+How-to guides
+-------------
+
+Step-by-step guides detailing information about working with OpenStack Charmed
+Operators, including key tasks for successful deployment and operations.
+
+.. toctree::
+   :maxdepth: 1
+
+   howto/index
+
+Concepts
+--------
+
+Dive deep into the concepts and details of how OpenStack services are setup and
+managed using OpenStack Charmed Operators.
+
+.. toctree::
+   :maxdepth: 1
+
+   concepts/index
+
+
+Reference material
+------------------
+
+Reference material for developers, operators and technical writers
+contributing to OpenStack Charmed Operators.
+
+.. toctree::
+   :maxdepth: 1
+
+   Release Notes <release-notes/index>
+   List of Charms <reference/openstack-charms>
+   reference/index
 
-   getting-started
-   find-us
-   openstack-charms
-   support-notes
-   creating-charms
-   how-to-contribute
-   author-guides/index
-   rotas
-   release-policy
-   release-schedule
-   release-notes
 
 .. LINKS
 .. _OpenStack Charms: https://launchpad.net/openstack-charms
+.. _MAAS: https://maas.io/
+.. _Juju: https://juju.is/

doc/source/reference/creating-charms.rst

@@ -9,8 +9,4 @@ Create A Charm
    :maxdepth: 1
 
    feature-specification
-   charm-anatomy
-   new-sdn-charm
-   new-api-charm
-   new-manila-charm
-
+   /concepts/charm-anatomy

doc/source/reference/feature-specification.rst

@@ -21,7 +21,7 @@ to use as a base for new specs.
 
 Recommended work flow for introducing a new feature specification:
 
-1. Have a :doc:`conversation <find-us>` with core charmers to avoid overlapping
+1. Have a :doc:`conversation </community>` with core charmers to avoid overlapping
    or duplicate work.
 
 2. Discuss the high-level design with core charmers to arrive at an optimal
@@ -37,10 +37,10 @@ Recommended work flow for introducing a new feature specification:
 5. Support the proposal by including relevant bug references in the
    specification.
 
-6. Circulate the proposal on the :doc:`mailing list <find-us>` to ensure wider
+6. Circulate the proposal on the :doc:`mailing list </community>` to ensure wider
    visibility.
 
-7. Engage in :doc:`further discussion <find-us>` surrounding the spec proposal
+7. Engage in :doc:`further discussion </community>` surrounding the spec proposal
    and the mailing list post so that it can be reviewed and landed.
 
 .. LINKS

doc/source/reference/index.rst

@@ -0,0 +1,16 @@
+=========
+Reference
+=========
+
+This section contains reference materials
+
+.. toctree::
+   :maxdepth: 1
+
+   how-to-contribute
+   support-notes
+   creating-charms
+   openstack-charms
+   reactive-handlers-optimization
+   rotas
+   release-policy

doc/source/reference/making-a-change.rst

@@ -146,4 +146,4 @@ For details on getting started with `Launchpad`_ development, please read the `L
 <https://help.launchpad.net/Code>`_ after you have registered your account.
 
 Also please do reach out to us on IRC or the mailing list (see the :doc:`Talk
-to us <find-us>` page).
+to us </community>` page).

doc/source/release-notes/index.rst

@@ -1,5 +1,5 @@
 =============
-Release Notes
+Release notes
 =============
 
 **Pending Release Notes**

doc/test/redirect-tests.txt

@@ -0,0 +1,57 @@
+# This file contains tests for redirects to handle existing URLs for
+# documentation that has been moved. See
+# https://docs.openstack.org/whereto/latest/ for details.
+
+# No redirects
+/ 200
+/charm-guide 200
+/charm-guide/index.html 200
+/some/other/project/config-openstack.html 200
+
+/charm-guide/latest/find-us.html 301 /charm-guide/latest/community.html
+/charm-guide/latest/charm-anatomy.html 301 /charm-guide/latest/concepts/charm-anatomy.html
+/charm-guide/latest/charms-and-bundles.html 301 /charm-guide/latest/getting-started/charms-and-bundles.html
+/charm-guide/latest/getting-started.html 301 /charm-guide/latest/getting-started/index.html
+/charm-guide/latest/new-api-charm.html 301 /charm-guide/latest/howto/new-api-charm.html
+/charm-guide/latest/new-manila-charm.html 301 /charm-guide/latest/howto/new-manila-charm.html
+/charm-guide/latest/new-sdn-charm.html 301 /charm-guide/latest/howto/new-sdn-charm.html
+/charm-guide/latest/backport-policy.html 301 /charm-guide/latest/reference/backport-policy.html
+/charm-guide/latest/coding-guidelines.html 301 /charm-guide/latest/reference/coding-guidelines.html
+/charm-guide/latest/creating-charms.html 301 /charm-guide/latest/reference/creating-charms.html
+/charm-guide/latest/feature-specification.html 301 /charm-guide/latest/reference/feature-specification.html
+/charm-guide/latest/how-to-contribute.html 301 /charm-guide/latest/reference/how-to-contribute.html
+/charm-guide/latest/making-a-change.html 301 /charm-guide/latest/reference/making-a-change.html
+/charm-guide/latest/openstack-charms.html 301 /charm-guide/latest/reference/openstack-charms.html
+/charm-guide/latest/author-guides/reactive-handlers-optimization.html 301 /charm-guide/latest/reference/reactive-handlers-optimization.html
+/charm-guide/latest/release-policy.html 301 /charm-guide/latest/reference/release-policy.html
+/charm-guide/latest/release-schedule.html 301 /charm-guide/latest/reference/release-schedule.html
+/charm-guide/latest/release-timeline-2008.html 301 /charm-guide/latest/reference/release-timeline-2008.html
+/charm-guide/latest/release-timeline-2010.html 301 /charm-guide/latest/reference/release-timeline-2010.html
+/charm-guide/latest/release-timeline-2101.html 301 /charm-guide/latest/reference/release-timeline-2101.html
+/charm-guide/latest/release-timeline-2104.html 301 /charm-guide/latest/reference/release-timeline-2104.html
+/charm-guide/latest/release-timeline-2110.html 301 /charm-guide/latest/reference/release-timeline-2110.html
+/charm-guide/latest/rotas.html 301 /charm-guide/latest/reference/rotas.html
+/charm-guide/latest/support-notes.html 301 /charm-guide/latest/reference/support-notes.html
+/charm-guide/latest/testing.html 301 /charm-guide/latest/reference/testing.html
+/charm-guide/latest/1610.html 301 /charm-guide/latest/release-notes/1610.html
+/charm-guide/latest/1702.html 301 /charm-guide/latest/release-notes/1702.html
+/charm-guide/latest/1708.html 301 /charm-guide/latest/release-notes/1708.html
+/charm-guide/latest/1711.html 301 /charm-guide/latest/release-notes/1711.html
+/charm-guide/latest/1802.html 301 /charm-guide/latest/release-notes/1802.html
+/charm-guide/latest/1805.html 301 /charm-guide/latest/release-notes/1805.html
+/charm-guide/latest/1808.html 301 /charm-guide/latest/release-notes/1808.html
+/charm-guide/latest/1811.html 301 /charm-guide/latest/release-notes/1811.html
+/charm-guide/latest/1904.html 301 /charm-guide/latest/release-notes/1904.html
+/charm-guide/latest/1907.html 301 /charm-guide/latest/release-notes/1907.html
+/charm-guide/latest/1910.html 301 /charm-guide/latest/release-notes/1910.html
+/charm-guide/latest/2002.html 301 /charm-guide/latest/release-notes/2002.html
+/charm-guide/latest/2005.html 301 /charm-guide/latest/release-notes/2005.html
+/charm-guide/latest/2008.html 301 /charm-guide/latest/release-notes/2008.html
+/charm-guide/latest/2010.html 301 /charm-guide/latest/release-notes/2010.html
+/charm-guide/latest/2101.html 301 /charm-guide/latest/release-notes/2101.html
+/charm-guide/latest/2103_Trilio.html 301 /charm-guide/latest/release-notes/2103_Trilio.html
+/charm-guide/latest/2104.html 301 /charm-guide/latest/release-notes/2104.html
+/charm-guide/latest/2106_Trilio.html 301 /charm-guide/latest/release-notes/2106_Trilio.html
+/charm-guide/latest/2110.html 301 /charm-guide/latest/release-notes/2110.html
+/charm-guide/latest/release-notes.html 301 /charm-guide/latest/release-notes/index.html
+/charm-guide/latest/release-notes-template.html 301 /charm-guide/latest/release-notes/release-notes-template.html

requirements.txt

@@ -6,3 +6,4 @@ pbr!=2.1.0,>=2.0.0 # Apache-2.0
 
 sphinx>=2.0.0,!=2.1.0 # BSD
 openstackdocstheme>=2.2.1 # Apache-2.0
+whereto>=0.3.0 # Apache-2.0

tox.ini

@@ -13,3 +13,4 @@ commands = {posargs}
 
 [testenv:docs]
 commands = sphinx-build -a -W -d doc/build/doctrees -b html doc/source doc/build/html
+           whereto doc/source/_extra/.htaccess doc/test/redirect-tests.txt