Make doc/source directory compliant with design in spec

The following spec defines what each project's doc/source
directory is supposed to look like:

https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html

I had not yet moved existing content to follow this design.
This patch does that, moving the devref to the
'contributor' directory.  It also moves the CLI
related documentation into the 'cli' directory.  I have
updated the autodoc generation to now create the api
documentation in 'doc/source/contributor/api'.

This patch also creates a template for future documentation
contribution.  I have created all of the directories
recommended by the spec and have included documentation
as to what should go in each directory.

The index file is updated to point at the new locations for
existing content.

'doc/.gitignore' is updated so that it won't complain about the
automatically generated 'doc/contributor/api' directory.

Change-Id: I55c50fa0b7c1d06c91e40dbcfd11b1c8e8378aa6

doc/.gitignore

@@ -1,3 +1,3 @@
 _build/*
-source/api/*
+source/contributor/api/*
 .autogenerated

doc/generate_autodoc_index.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-SOURCEDIR=doc/source/api
+SOURCEDIR=doc/source/contributor/api
 
 if [ ! -d ${SOURCEDIR} ] ; then
     mkdir -p ${SOURCEDIR}

doc/source/admin/README.rst

@@ -0,0 +1,16 @@
+===================================
+Cinder Administration Documentation
+===================================
+
+Introduction:
+-------------
+
+This directory is intended to hold any documentation that relates to
+how to run or operate Cinder.  Previously, this content was in the
+admin-guide section of openstack-manuals.
+
+The full spec for organization of documentation may be seen in the
+`OS Manuals Migration Spec
+<https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html>`.
+
+

doc/source/cli/README.rst

@@ -0,0 +1,17 @@
+==========================
+Cinder CLI Documentation
+==========================
+
+Introduction:
+-------------
+
+This directory is intended to hold any documentation that relates to
+Cinder's Command Line Interface.  Note that this directory is intended for
+basic descriptions of the commands supported, similar to what you would find
+with a 'man page'.  Tutorials or step-by-step guides should go into
+'doc/source/admin' or 'doc/source/user' depending on the target audience.
+
+The full spec for organization of documentation may be seen in the
+`OS Manuals Migration Spec
+<https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html>`.
+

doc/source/cli/cli-set-quotas.rst

@@ -56,6 +56,4 @@ values.
 .. toctree::
    :maxdepth: 2
 
-   cli-set-compute-quotas.rst
    cli-cinder-quotas.rst
-   cli-networking-advanced-quotas.rst

doc/source/configuration/README.rst

@@ -0,0 +1,17 @@
+==================================
+Cinder Configuration Documentation
+==================================
+
+Introduction:
+-------------
+
+This directory is intended to hold any documentation that relates to
+how to configure Cinder.  It is intended that some of this content
+be automatically generated in the future.  At the moment, however, it
+is not.  Changes to configuration options for Cinder or its drivers
+needs to be put under this directory.
+
+The full spec for organization of documentation may be seen in the
+`OS Manuals Migration Spec
+<https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html>`.
+

doc/source/contributor/README.rst

@@ -0,0 +1,17 @@
+================================
+Cinder Contributor Documentation
+================================
+
+Introduction:
+-------------
+
+This directory is intended to hold any documentation that relates to
+how to contirbute to Cinder or how the project is managed.  Some of this
+content was previous under 'developer' in openstack-manuals.  The content
+of the documentation, however, goes beyond just developers to anyone
+contributing to the project, thus the change in naming.
+
+The full spec for organization of documentation may be seen in the
+`OS Manuals Migration Spec
+<https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html>`.
+

doc/source/contributor/attach_detach_conventions_v2.rst

@@ -11,9 +11,9 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-=============================
-Volume Attach/Detach workflow
-=============================
+==================================
+Volume Attach/Detach workflow - V2
+==================================
 
 Previously there were six API calls associated with attach/detach of volumes in
 Cinder (3 calls for each operation).  As the projects grew and the

doc/source/contributor/index.rst

@@ -15,8 +15,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-Developer Guide
-===============
+Contributor Guide
+=================
 
 In this section you will find information on Cinder's lower level programming
 APIs.
@@ -69,7 +69,7 @@ API Reference
 .. toctree::
    :maxdepth: 3
 
-   ../api/autoindex
+   ./api/autoindex
 
 Module Reference
 ----------------

doc/source/index.rst

@@ -49,13 +49,13 @@ Admin Docs
 
    admin/blockstorage
 
-Developer Docs
-==============
+Contributor/Developer Docs
+==========================
 
 .. toctree::
    :maxdepth: 1
 
-   devref/index
+   contributor/index
    scheduler-filters
    scheduler-weights
    upgrade
@@ -66,10 +66,10 @@ Command Line Interface Documentation
 .. toctree::
    :maxdepth: 2
 
-   admin/cli-manage-volumes
-   admin/cli-set-quotas
-   admin/cli-cinder-quotas
-   admin/cli-cinder-scheduling
+   cli/cli-manage-volumes
+   cli/cli-set-quotas
+   cli/cli-cinder-quotas
+   cli/cli-cinder-scheduling
 
 Drivers
 =======

doc/source/reference/README.rst

@@ -0,0 +1,15 @@
+==============================
+Cinder Reference Documentation
+==============================
+
+Introduction:
+-------------
+
+This directory is intended to hold any reference documentation for Cinder
+that doesn't fit into 'install', 'contributor', 'configuration', 'cli',
+'admin', or 'user' categories.
+
+The full spec for organization of documentation may be seen in the
+`OS Manuals Migration Spec
+<https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html>`.
+

doc/source/user/README.rst

@@ -0,0 +1,16 @@
+==========================
+Cinder User Documentation
+==========================
+
+Introduction:
+-------------
+
+This directory is intended to hold any documentation that helps Cinder
+end-users.  This can include concept guides, tutorials, step-by-step guides
+for using the CLI, etc.  Note that documentation this is focused on
+administrative actions should go into 'doc/source/admin'.
+
+The full spec for organization of documentation may be seen in the
+`OS Manuals Migration Spec
+<https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html>`.
+