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
This commit is contained in:
Jay S. Bryant 2017-07-19 15:21:07 -05:00
parent 7c8901e764
commit 1423480fb6
46 changed files with 113 additions and 17 deletions

2
doc/.gitignore vendored
View File

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

View File

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

View File

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

17
doc/source/cli/README.rst Normal file
View File

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

View File

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

View File

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

View File

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

View File

@ -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

View File

@ -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
----------------

View File

@ -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
=======

View File

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

View File

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