From 1423480fb6e845114cc734eaf3dc0c37c2c187cc Mon Sep 17 00:00:00 2001 From: "Jay S. Bryant" Date: Wed, 19 Jul 2017 15:21:07 -0500 Subject: [PATCH] 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 | 2 +- doc/generate_autodoc_index.sh | 2 +- doc/source/admin/README.rst | 16 ++++++++++++++++ doc/source/cli/README.rst | 17 +++++++++++++++++ doc/source/{admin => cli}/cli-cinder-quotas.rst | 0 .../{admin => cli}/cli-cinder-scheduling.rst | 0 .../{admin => cli}/cli-manage-volumes.rst | 0 doc/source/{admin => cli}/cli-set-quotas.rst | 2 -- doc/source/configuration/README.rst | 17 +++++++++++++++++ doc/source/contributor/README.rst | 17 +++++++++++++++++ .../addmethod.openstackapi.rst | 0 .../{devref => contributor}/api.apache.rst | 0 doc/source/{devref => contributor}/api.rst | 0 .../api_conditional_updates.rst | 0 .../api_microversion_dev.rst | 0 .../api_microversion_history.rst | 0 .../{devref => contributor}/architecture.rst | 0 .../attach_detach_conventions.rst | 0 .../attach_detach_conventions_v2.rst | 6 +++--- doc/source/{devref => contributor}/auth.rst | 0 doc/source/{devref => contributor}/cinder.rst | 0 doc/source/{devref => contributor}/database.rst | 0 .../development.environment.rst | 0 doc/source/{devref => contributor}/drivers.rst | 0 doc/source/{devref => contributor}/fakes.rst | 0 doc/source/{devref => contributor}/gerrit.rst | 0 doc/source/{devref => contributor}/gmr.rst | 0 doc/source/{devref => contributor}/groups.rst | 0 doc/source/{devref => contributor}/i18n.rst | 0 doc/source/{devref => contributor}/index.rst | 6 +++--- doc/source/{devref => contributor}/jenkins.rst | 0 .../{devref => contributor}/launchpad.rst | 0 .../{devref => contributor}/migration.rst | 0 .../{devref => contributor}/releasenotes.rst | 0 .../{devref => contributor}/replication.rst | 0 .../rolling.upgrades.rst | 0 doc/source/{devref => contributor}/rpc.rst | 0 .../{devref => contributor}/scheduler.rst | 0 doc/source/{devref => contributor}/services.rst | 0 doc/source/{devref => contributor}/testing.rst | 0 .../{devref => contributor}/threading.rst | 0 .../{devref => contributor}/user_messages.rst | 0 doc/source/{devref => contributor}/volume.rst | 0 doc/source/index.rst | 14 +++++++------- doc/source/reference/README.rst | 15 +++++++++++++++ doc/source/user/README.rst | 16 ++++++++++++++++ 46 files changed, 113 insertions(+), 17 deletions(-) create mode 100644 doc/source/admin/README.rst create mode 100644 doc/source/cli/README.rst rename doc/source/{admin => cli}/cli-cinder-quotas.rst (100%) rename doc/source/{admin => cli}/cli-cinder-scheduling.rst (100%) rename doc/source/{admin => cli}/cli-manage-volumes.rst (100%) rename doc/source/{admin => cli}/cli-set-quotas.rst (96%) create mode 100644 doc/source/configuration/README.rst create mode 100644 doc/source/contributor/README.rst rename doc/source/{devref => contributor}/addmethod.openstackapi.rst (100%) rename doc/source/{devref => contributor}/api.apache.rst (100%) rename doc/source/{devref => contributor}/api.rst (100%) rename doc/source/{devref => contributor}/api_conditional_updates.rst (100%) rename doc/source/{devref => contributor}/api_microversion_dev.rst (100%) rename doc/source/{devref => contributor}/api_microversion_history.rst (100%) rename doc/source/{devref => contributor}/architecture.rst (100%) rename doc/source/{devref => contributor}/attach_detach_conventions.rst (100%) rename doc/source/{devref => contributor}/attach_detach_conventions_v2.rst (98%) rename doc/source/{devref => contributor}/auth.rst (100%) rename doc/source/{devref => contributor}/cinder.rst (100%) rename doc/source/{devref => contributor}/database.rst (100%) rename doc/source/{devref => contributor}/development.environment.rst (100%) rename doc/source/{devref => contributor}/drivers.rst (100%) rename doc/source/{devref => contributor}/fakes.rst (100%) rename doc/source/{devref => contributor}/gerrit.rst (100%) rename doc/source/{devref => contributor}/gmr.rst (100%) rename doc/source/{devref => contributor}/groups.rst (100%) rename doc/source/{devref => contributor}/i18n.rst (100%) rename doc/source/{devref => contributor}/index.rst (97%) rename doc/source/{devref => contributor}/jenkins.rst (100%) rename doc/source/{devref => contributor}/launchpad.rst (100%) rename doc/source/{devref => contributor}/migration.rst (100%) rename doc/source/{devref => contributor}/releasenotes.rst (100%) rename doc/source/{devref => contributor}/replication.rst (100%) rename doc/source/{devref => contributor}/rolling.upgrades.rst (100%) rename doc/source/{devref => contributor}/rpc.rst (100%) rename doc/source/{devref => contributor}/scheduler.rst (100%) rename doc/source/{devref => contributor}/services.rst (100%) rename doc/source/{devref => contributor}/testing.rst (100%) rename doc/source/{devref => contributor}/threading.rst (100%) rename doc/source/{devref => contributor}/user_messages.rst (100%) rename doc/source/{devref => contributor}/volume.rst (100%) create mode 100644 doc/source/reference/README.rst create mode 100644 doc/source/user/README.rst diff --git a/doc/.gitignore b/doc/.gitignore index 291b04e45..3bdf75a34 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,3 +1,3 @@ _build/* -source/api/* +source/contributor/api/* .autogenerated diff --git a/doc/generate_autodoc_index.sh b/doc/generate_autodoc_index.sh index bdfa73a49..335f72cfa 100755 --- a/doc/generate_autodoc_index.sh +++ b/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} diff --git a/doc/source/admin/README.rst b/doc/source/admin/README.rst new file mode 100644 index 000000000..5debfdd7e --- /dev/null +++ b/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 +`. + + diff --git a/doc/source/cli/README.rst b/doc/source/cli/README.rst new file mode 100644 index 000000000..26bbd57dd --- /dev/null +++ b/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 +`. + diff --git a/doc/source/admin/cli-cinder-quotas.rst b/doc/source/cli/cli-cinder-quotas.rst similarity index 100% rename from doc/source/admin/cli-cinder-quotas.rst rename to doc/source/cli/cli-cinder-quotas.rst diff --git a/doc/source/admin/cli-cinder-scheduling.rst b/doc/source/cli/cli-cinder-scheduling.rst similarity index 100% rename from doc/source/admin/cli-cinder-scheduling.rst rename to doc/source/cli/cli-cinder-scheduling.rst diff --git a/doc/source/admin/cli-manage-volumes.rst b/doc/source/cli/cli-manage-volumes.rst similarity index 100% rename from doc/source/admin/cli-manage-volumes.rst rename to doc/source/cli/cli-manage-volumes.rst diff --git a/doc/source/admin/cli-set-quotas.rst b/doc/source/cli/cli-set-quotas.rst similarity index 96% rename from doc/source/admin/cli-set-quotas.rst rename to doc/source/cli/cli-set-quotas.rst index 6b305be3d..305ea9dbe 100644 --- a/doc/source/admin/cli-set-quotas.rst +++ b/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 diff --git a/doc/source/configuration/README.rst b/doc/source/configuration/README.rst new file mode 100644 index 000000000..e759b64ef --- /dev/null +++ b/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 +`. + diff --git a/doc/source/contributor/README.rst b/doc/source/contributor/README.rst new file mode 100644 index 000000000..127540cb5 --- /dev/null +++ b/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 +`. + diff --git a/doc/source/devref/addmethod.openstackapi.rst b/doc/source/contributor/addmethod.openstackapi.rst similarity index 100% rename from doc/source/devref/addmethod.openstackapi.rst rename to doc/source/contributor/addmethod.openstackapi.rst diff --git a/doc/source/devref/api.apache.rst b/doc/source/contributor/api.apache.rst similarity index 100% rename from doc/source/devref/api.apache.rst rename to doc/source/contributor/api.apache.rst diff --git a/doc/source/devref/api.rst b/doc/source/contributor/api.rst similarity index 100% rename from doc/source/devref/api.rst rename to doc/source/contributor/api.rst diff --git a/doc/source/devref/api_conditional_updates.rst b/doc/source/contributor/api_conditional_updates.rst similarity index 100% rename from doc/source/devref/api_conditional_updates.rst rename to doc/source/contributor/api_conditional_updates.rst diff --git a/doc/source/devref/api_microversion_dev.rst b/doc/source/contributor/api_microversion_dev.rst similarity index 100% rename from doc/source/devref/api_microversion_dev.rst rename to doc/source/contributor/api_microversion_dev.rst diff --git a/doc/source/devref/api_microversion_history.rst b/doc/source/contributor/api_microversion_history.rst similarity index 100% rename from doc/source/devref/api_microversion_history.rst rename to doc/source/contributor/api_microversion_history.rst diff --git a/doc/source/devref/architecture.rst b/doc/source/contributor/architecture.rst similarity index 100% rename from doc/source/devref/architecture.rst rename to doc/source/contributor/architecture.rst diff --git a/doc/source/devref/attach_detach_conventions.rst b/doc/source/contributor/attach_detach_conventions.rst similarity index 100% rename from doc/source/devref/attach_detach_conventions.rst rename to doc/source/contributor/attach_detach_conventions.rst diff --git a/doc/source/devref/attach_detach_conventions_v2.rst b/doc/source/contributor/attach_detach_conventions_v2.rst similarity index 98% rename from doc/source/devref/attach_detach_conventions_v2.rst rename to doc/source/contributor/attach_detach_conventions_v2.rst index 866809716..e5539f12f 100644 --- a/doc/source/devref/attach_detach_conventions_v2.rst +++ b/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 diff --git a/doc/source/devref/auth.rst b/doc/source/contributor/auth.rst similarity index 100% rename from doc/source/devref/auth.rst rename to doc/source/contributor/auth.rst diff --git a/doc/source/devref/cinder.rst b/doc/source/contributor/cinder.rst similarity index 100% rename from doc/source/devref/cinder.rst rename to doc/source/contributor/cinder.rst diff --git a/doc/source/devref/database.rst b/doc/source/contributor/database.rst similarity index 100% rename from doc/source/devref/database.rst rename to doc/source/contributor/database.rst diff --git a/doc/source/devref/development.environment.rst b/doc/source/contributor/development.environment.rst similarity index 100% rename from doc/source/devref/development.environment.rst rename to doc/source/contributor/development.environment.rst diff --git a/doc/source/devref/drivers.rst b/doc/source/contributor/drivers.rst similarity index 100% rename from doc/source/devref/drivers.rst rename to doc/source/contributor/drivers.rst diff --git a/doc/source/devref/fakes.rst b/doc/source/contributor/fakes.rst similarity index 100% rename from doc/source/devref/fakes.rst rename to doc/source/contributor/fakes.rst diff --git a/doc/source/devref/gerrit.rst b/doc/source/contributor/gerrit.rst similarity index 100% rename from doc/source/devref/gerrit.rst rename to doc/source/contributor/gerrit.rst diff --git a/doc/source/devref/gmr.rst b/doc/source/contributor/gmr.rst similarity index 100% rename from doc/source/devref/gmr.rst rename to doc/source/contributor/gmr.rst diff --git a/doc/source/devref/groups.rst b/doc/source/contributor/groups.rst similarity index 100% rename from doc/source/devref/groups.rst rename to doc/source/contributor/groups.rst diff --git a/doc/source/devref/i18n.rst b/doc/source/contributor/i18n.rst similarity index 100% rename from doc/source/devref/i18n.rst rename to doc/source/contributor/i18n.rst diff --git a/doc/source/devref/index.rst b/doc/source/contributor/index.rst similarity index 97% rename from doc/source/devref/index.rst rename to doc/source/contributor/index.rst index 4357e250b..8b4c98be0 100644 --- a/doc/source/devref/index.rst +++ b/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 ---------------- diff --git a/doc/source/devref/jenkins.rst b/doc/source/contributor/jenkins.rst similarity index 100% rename from doc/source/devref/jenkins.rst rename to doc/source/contributor/jenkins.rst diff --git a/doc/source/devref/launchpad.rst b/doc/source/contributor/launchpad.rst similarity index 100% rename from doc/source/devref/launchpad.rst rename to doc/source/contributor/launchpad.rst diff --git a/doc/source/devref/migration.rst b/doc/source/contributor/migration.rst similarity index 100% rename from doc/source/devref/migration.rst rename to doc/source/contributor/migration.rst diff --git a/doc/source/devref/releasenotes.rst b/doc/source/contributor/releasenotes.rst similarity index 100% rename from doc/source/devref/releasenotes.rst rename to doc/source/contributor/releasenotes.rst diff --git a/doc/source/devref/replication.rst b/doc/source/contributor/replication.rst similarity index 100% rename from doc/source/devref/replication.rst rename to doc/source/contributor/replication.rst diff --git a/doc/source/devref/rolling.upgrades.rst b/doc/source/contributor/rolling.upgrades.rst similarity index 100% rename from doc/source/devref/rolling.upgrades.rst rename to doc/source/contributor/rolling.upgrades.rst diff --git a/doc/source/devref/rpc.rst b/doc/source/contributor/rpc.rst similarity index 100% rename from doc/source/devref/rpc.rst rename to doc/source/contributor/rpc.rst diff --git a/doc/source/devref/scheduler.rst b/doc/source/contributor/scheduler.rst similarity index 100% rename from doc/source/devref/scheduler.rst rename to doc/source/contributor/scheduler.rst diff --git a/doc/source/devref/services.rst b/doc/source/contributor/services.rst similarity index 100% rename from doc/source/devref/services.rst rename to doc/source/contributor/services.rst diff --git a/doc/source/devref/testing.rst b/doc/source/contributor/testing.rst similarity index 100% rename from doc/source/devref/testing.rst rename to doc/source/contributor/testing.rst diff --git a/doc/source/devref/threading.rst b/doc/source/contributor/threading.rst similarity index 100% rename from doc/source/devref/threading.rst rename to doc/source/contributor/threading.rst diff --git a/doc/source/devref/user_messages.rst b/doc/source/contributor/user_messages.rst similarity index 100% rename from doc/source/devref/user_messages.rst rename to doc/source/contributor/user_messages.rst diff --git a/doc/source/devref/volume.rst b/doc/source/contributor/volume.rst similarity index 100% rename from doc/source/devref/volume.rst rename to doc/source/contributor/volume.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 7cd88da19..524f62832 100644 --- a/doc/source/index.rst +++ b/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 ======= diff --git a/doc/source/reference/README.rst b/doc/source/reference/README.rst new file mode 100644 index 000000000..fd0afd4ef --- /dev/null +++ b/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 +`. + diff --git a/doc/source/user/README.rst b/doc/source/user/README.rst new file mode 100644 index 000000000..27b70598c --- /dev/null +++ b/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 +`. +