Merge "Make doc/source directory compliant with design in spec"

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>`.
+