Docs: Arrange Contributor Guide

Change-Id: Ibda21080a200e4ea552d74a197b33381a1dd8964

.gitignore

@@ -39,7 +39,7 @@ output/*/index.html
 
 # Sphinx
 doc/build
-doc/source/api
+doc/source/contributor/api
 
 # pbr generates these
 AUTHORS

doc/source/configuration/index.rst

@@ -1,8 +1,8 @@
 .. _configuring:
 
-=====================
-Configuration Options
-=====================
+===================
+Configuration Guide
+===================
 
 This section provides a list of all possible options for each configuration
 file.

doc/source/contributing.rst

@@ -1,4 +0,0 @@
-============
-Contributing
-============
-.. include:: ../../CONTRIBUTING.rst

doc/source/contributor/architecture.rst

@@ -0,0 +1,136 @@
+============
+Architecture
+============
+
+High Level Architecture
+=======================
+.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
+    high_level_architecture.png
+    :alt: Solution Overview
+    :width: 600
+    :align: center
+
+The system is built from independent services and a scalable *Workflow
+engine* that ties them together:
+
+API Service
+===========
+
+.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
+    karbor-api.png
+    :width: 600
+
+These top-level north-bound APIs expose Application Data Protection services to
+the Karbor user.
+
+The purpose of the services is to maximize flexibility and accommodate for
+(hopefully) any kind of protection for any type of resource, whether it is a
+basic OpenStack resource (such as a VM, Volume, Image, etc.) or some ancillary
+resource within an application system that is not managed in OpenStack (such as
+a hardware device, an external database, etc.).
+
+
+Resource (Protectable) API
+--------------------------
+
+Enables the Karbor user to access information about which resource types are
+protectable (i.e. can be protected by Karbor).  In addition, enables the user to
+get  additional information on each resource type, such as a list of actual
+instances and their dependencies.
+
+Provider API
+------------
+
+Enables the Karbor user to list available providers and get parameters and
+result schema super-set for all plugins of a specific Provider.
+
+Plan API
+--------
+
+This API enables the Karbor user to access the protection Plan registry and do
+the following operations:
+
+-  Plan CRUD.
+-  List Plans.
+-  Starting and suspending of plans.
+
+Automatic Operation API
+-----------------------
+
+This API enables the Karbor user to manage protection Operations:
+
+-  Create a checkpoint for a given Protection Plan.
+-  Delete unneeded checkpoints from the provider.
+-  Query the status on a given Operation ID.
+
+Checkpoint API
+--------------
+
+This API enables the Karbor user to access and manage checkpoints stored in
+the protection provider:
+
+-  List all checkpoints given a Bank ID.
+-  Show Information on a given checkpoint ID.
+-  Delete a checkpoint.
+-  Create a checkpoint.
+
+Restore API
+-----------
+
+This API enables the Karbor user to restore a checkpoint onto a restore target:
+
+-  Create restored system from a checkpoint.
+
+Operation Engine Service
+========================
+
+This subsystem is responsible for scheduling and orchestrating the execution of
+*Protection Plans*.
+
+The implementation can be replaced by any other external solution since it uses
+only functions that are available through the north-bound API.
+
+Once an entity is created, it can be tracked through the north-bound API,
+so monitoring the operations is independent from the scheduler.
+
+It will be responsible for the automatic execution of specific operations
+and tracking them.
+
+Automatic Operation
+-------------------
+
+Automatic operations are the core of the scheduler. They define higher level
+automatic logic. A simple scenario is a set of scheduled operations that
+perform basic APIs at a specific trigger. There will also be complex scheduling
+policies available that perform multiple north-bound basic APIs.
+
+Trigger Engine
+--------------
+
+This sub-component of the schedule service is responsible for generating
+triggers, which begin the execution of the Plan Orchestration.
+
+It can be done based on a timer or an event collector, based on implementation.
+
+In the first Karbor reference implementation, the trigger engine will only
+provide time-based triggers.
+
+Scheduled Operation
+-------------------
+
+This sub-component of the schedule service is responsible for holding the
+mapping between a trigger and operation(s).
+
+Protection Service
+==================
+
+This subsystem is responsible for handling the following tasks:
+
+-  Operation Execution
+-  Protection Provider management
+
+WorkFlow Engine
+---------------
+
+This pluggable component is responsible for executing and orchestrating the
+flow of the plan across all protection providers.

doc/source/contributor/devref/index.rst

@@ -1,5 +1,5 @@
-Karobr Developer Reference
-==========================
+Developer Reference
+===================
 
 Code Reference
 --------------

doc/source/contributor/devstack-installation.rst

@@ -1,6 +1,6 @@
-======================================
-Devstack Installation (for developers)
-======================================
+=====================
+Devstack Installation
+=====================
 
 This type of installation is for developers or testing, and not for production.
 

doc/source/contributor/index.rst

@@ -0,0 +1,36 @@
+=========================
+Contributor Documentation
+=========================
+
+.. toctree::
+   :maxdepth: 2
+
+   architecture
+   devstack-installation
+   ../specs/index
+   devref/index
+
+
+Communication and Meetings
+==========================
+
+- Karbor Launchpad Link: \ https://launchpad.net/karbor
+- Karbor Code Review: \ https://review.openstack.org/#/q/karbor+status:open,n,z
+- Karbor Code Repository: \ https://github.com/openstack/karbor
+- Karbor daily IRC Channel: #openstack-karbor
+- Karbor IRC Meeting: every two weeks (on odd weeks) on Tuesday at 0900 UTC in
+  #openstack-meeting (IRC webclient).
+
+  ICS File: http://eavesdrop.openstack.org/calendars/karbor-team-meeting.ics
+
+  Additional Info: https://wiki.openstack.org/wiki/Meetings/karbor
+
+Additional References
+=====================
+
+- `OpenStack Tokyo Summit 2015 talk <http://www.slideshare.net/gampel/openstack-tokyo-talk-application-data-protection-service>`_
+- `OpenStack Austin Summit 2016 talk <https://www.youtube.com/watch?v=_tVYuW_YMB8>`_
+- `OpenStack Barcelona Summit 2016 talk <https://www.youtube.com/watch?v=YFfcmGMn3M4>`_
+- `OpenStack Boston Summit 2017 talk <https://www.youtube.com/watch?v=0l3zcmNboDQ>`_
+- `Karbor overview slide <https://docs.google.com/presentation/d/1JYO1VIlTkGTF6lvKEMcsHkaST3mYFxuarpcNTJ3HBhk/edit?usp=sharing>`_
+- `Karbor overview blog  <http://blog.gampel.net/2015/12/karbor-application-data-protection-for.html>`_

doc/source/index.rst

@@ -16,21 +16,18 @@ standard framework of APIs and services that allows vendors to provide plugins
 through a unified interface
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   install/index
-   configuration/index
 
 Using Karbor
 ============
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    readme
-   devstack-installation
    usage
-   contributing
-   releasenotes
+   install/index
+   configuration/index
 
 Available Plugins
 =================
@@ -41,19 +38,21 @@ Available Plugins
    protectable_plugins
    protection_plugins
 
-Karbor Code Reference
-=====================
+Contributor Docs
+================
+
+.. toctree::
+   :maxdepth: 2
+
+   contributor/index
+
+Release Notes
+=============
+
 .. toctree::
    :maxdepth: 1
 
-   devref/index
-
-Karbor Specs
-============
-.. toctree::
-   :maxdepth: 1
-
-   specs/index
+   releasenotes
 
 Indices and tables
 ==================

doc/source/install/index.rst

@@ -1,6 +1,6 @@
-============
-Installation
-============
+==================
+Installation Guide
+==================
 
 .. toctree::
    :maxdepth: 1

doc/source/readme.rst

@@ -3,8 +3,6 @@
 Introduction
 ============
 
-.. contents:: :depth: 2
-
 What is Karbor?
 ===============
 
@@ -137,155 +135,3 @@ protectables during set up as long as the protection provider can handle those
 entities. This flexibility means that Karbor is agnostic to the relationship
 between the resources being backed up.
 
-High Level Architecture
-=======================
-.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
-    high_level_architecture.png
-    :alt: Solution Overview
-    :width: 600
-    :align: center
-
-The system is built from independent services and a scalable *Workflow
-engine* that ties them together:
-
-Karbor API Service
-==================
-
-.. image:: https://raw.githubusercontent.com/openstack/karbor/master/doc/images/
-    karbor-api.png
-    :width: 600
-
-These top-level north-bound APIs expose Application Data Protection services to
-the Karbor user.
-
-The purpose of the services is to maximize flexibility and accommodate for
-(hopefully) any kind of protection for any type of resource, whether it is a
-basic OpenStack resource (such as a VM, Volume, Image, etc.) or some ancillary
-resource within an application system that is not managed in OpenStack (such as
-a hardware device, an external database, etc.).
-
-
-Resource (Protectable) API
---------------------------
-
-Enables the Karbor user to access information about which resource types are
-protectable (i.e. can be protected by Karbor).  In addition, enables the user to
-get  additional information on each resource type, such as a list of actual
-instances and their dependencies.
-
-Provider API
-------------
-
-Enables the Karbor user to list available providers and get parameters and
-result schema super-set for all plugins of a specific Provider.
-
-Plan API
---------
-
-This API enables the Karbor user to access the protection Plan registry and do
-the following operations:
-
--  Plan CRUD.
--  List Plans.
--  Starting and suspending of plans.
-
-Automatic Operation API
------------------------
-
-This API enables the Karbor user to manage protection Operations:
-
--  Create a checkpoint for a given Protection Plan.
--  Delete unneeded checkpoints from the provider.
--  Query the status on a given Operation ID.
-
-Checkpoint API
---------------
-
-This API enables the Karbor user to access and manage checkpoints stored in
-the protection provider:
-
--  List all checkpoints given a Bank ID.
--  Show Information on a given checkpoint ID.
--  Delete a checkpoint.
--  Create a checkpoint.
-
-Restore API
------------
-
-This API enables the Karbor user to restore a checkpoint onto a restore target:
-
--  Create restored system from a checkpoint.
-
-Karbor Schedule Service
-=======================
-
-This subsystem is responsible for scheduling and orchestrating the execution of
-*Protection Plans*.
-
-The implementation can be replaced by any other external solution since it uses
-only functions that are available through the north-bound API.
-
-Once an entity is created, it can be tracked through the north-bound API,
-so monitoring the operations is independent from the scheduler.
-
-It will be responsible for the automatic execution of specific operations
-and tracking them.
-
-Automatic Operation
--------------------
-
-Automatic operations are the core of the scheduler. They define higher level
-automatic logic. A simple scenario is a set of scheduled operations that
-perform basic APIs at a specific trigger. There will also be complex scheduling
-policies available that perform multiple north-bound basic APIs.
-
-Trigger Engine
---------------
-
-This sub-component of the schedule service is responsible for generating
-triggers, which begin the execution of the Plan Orchestration.
-
-It can be done based on a timer or an event collector, based on implementation.
-
-In the first Karbor reference implementation, the trigger engine will only
-provide time-based triggers.
-
-Scheduled Operation
--------------------
-
-This sub-component of the schedule service is responsible for holding the
-mapping between a trigger and operation(s).
-
-Karbor Protection Service
-=========================
-
-This subsystem is responsible for handling the following tasks:
-
--  Operation Execution
--  Protection Provider management
-
-WorkFlow Engine
----------------
-
-This pluggable component is responsible for executing and orchestrating the
-flow of the plan across all protection providers.
-
-Communication and Meetings
-==========================
-
-- Karbor Launchpad Link: \ https://launchpad.net/karbor
-- Karbor Code Review: \ https://review.openstack.org/#/q/karbor+status:open,n,z
-- Karbor Code Repository: \ https://github.com/openstack/karbor
-- Karbor daily IRC Channel: #openstack-karbor
-- Karbor weekly IRC Meeting on **even** Tuesday at 1500 UTC
-  and on **odd** Tuesday at 0900 UTC in
-  #openstack-meeting at freenode: \
-  https://wiki.openstack.org/wiki/Meetings/karbor
-
-Additional references
-=====================
-
-- `OpenStack Tokyo Summit 2015 talk <http://www.slideshare.net/gampel/openstack-tokyo-talk-application-data-protection-service>`_
-- `OpenStack Austin Summit 2016 talk <https://www.youtube.com/watch?v=_tVYuW_YMB8>`_
-- `Karbor overview slide <https://docs.google.com/presentation/d/1JYO1VIlTkGTF6lvKEMcsHkaST3mYFxuarpcNTJ3HBhk/edit?usp=sharing>`_
-- `Karbor overview blog  <http://blog.gampel.net/2015/12/karbor-application-data-protection-for.html>`_

doc/source/specs/index.rst

@@ -1,5 +1,5 @@
-Karbor Specs
-============
+Specs
+=====
 
 This section contains detailed specification documents for
 different features inside Karbor.

setup.cfg

@@ -92,4 +92,5 @@ autodoc_exclude_modules =
     karbor.services.protection.bank_plugins.*
     karbor.services.protection.protectable_plugins.*
     karbor.services.protection.protection_plugins.*
+api_doc_dir = contributor/api
 warnerrors = true

tox.ini

@@ -37,7 +37,7 @@ commands =
 [testenv:docs]
 whitelist_externals = rm
 commands = rm -rf doc/build
-           rm -rf doc/source/api
+           rm -rf doc/source/contributor/api
            python setup.py build_sphinx
 
 [testenv:debug]