cloud-admin-guide-rst: Rework orchestration layout

Remove hidden toctree and use a normal toctree.
Split up introduction into separate file.

This renders the content now on several separate files instead of one
very large file.

Compare the new output with:
http://docs.openstack.org/draft/admin-guide-cloud-rst/orchestration.html
http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-orchestration.html

Change-Id: Iff95d2d83abc1ef95bed5cd70b114a9724bdc57f

doc/admin-guide-cloud-rst/source/orchestration-auth-model.rst

@@ -1,12 +1,12 @@
-.. _orchestration-auth-model:
-
 .. highlight: ini
    :linenothreshold: 3
 
-   :orphan:
+.. _orchestration-auth-model:
 
+=================================
 Orchestration authorization model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================================
+
 
 Orchestration authorization model defines the process of authorization
 that orchestration module uses to authorize requests during so called
@@ -22,7 +22,7 @@ Currently, Orchestration provides two kinds of authorization models:
 * Authorization with OpenStack Identity trusts.
 
 Password authorization
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 Password authorization is the initial authorization model that was
 supported by Orchestration module. This kind of authorization requires
@@ -51,7 +51,7 @@ The following steps are executed for password authorization:
    owner.
 
 Keystone trusts authorization
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 OpenStack Identity trusts is a new authorization method available
 since the IceHouse release.
@@ -109,7 +109,7 @@ The following steps are executed for trusts authorization:
    AutoScaling event.
 
 Authorization model configuration
----------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Password authorization model had been the default authorization model
 enabled for the Orchestration module before the Kilo release. Since

doc/admin-guide-cloud-rst/source/orchestration-introduction.rst

@@ -0,0 +1,34 @@
+============
+Introduction
+============
+
+Orchestration is a tool for orchestrating clouds that automatically
+configures and deploys resources in stacks. Such deployments can be
+simple — like deploying WordPress on Ubuntu with an SQL back end.
+And they can be quite complex, like launching a group of servers that
+autoscale: starting and stopping based on realtime CPU loading
+information from the Telemetry module.
+
+Orchestration stacks are defined with templates, which are
+non-procedural documents describing tasks in terms of resources,
+parameters, inputs, constraints and dependencies. When Orchestration
+module was originally introduced, it worked with AWS CloudFormation
+templates, which are in JSON format.
+
+Now, Orchestration also executes HOT (Heat Orchestration Template)
+templates written in YAML: a terse notation that loosely follows
+Python/Ruby-type structural conventions (colons, returns,
+indentation), so it is more easy to write, parse, grep, generate with
+tools, and maintain source-code management systems.
+
+Orchestration can be accessed via the CLI, and using RESTful queries.
+Orchestration module provides both an OpenStack-native REST API and a
+CloudFormation-compatible Query API. Orchestration is also integrated
+with OpenStack dashboard in order to launch stacks from templates
+through a web interface.
+
+For more details on how to use Orchestration module through a command
+line, see `OpenStack Command-Line Interface Reference`_.
+
+.. Links
+.. _`OpenStack Command-Line Interface Reference`: http://docs.openstack.org/cli-reference

doc/admin-guide-cloud-rst/source/orchestration-stack-domain-users.rst

@@ -1,9 +1,10 @@
-.. _orchestration-stack-domain-users:
-
 .. highlight: ini
 
+.. _orchestration-stack-domain-users:
+
+==================
 Stack domain users
-~~~~~~~~~~~~~~~~~~
+==================
 
 Orchestration stack domain users allows Orchestration module to
 authorize inside VMs booted and execute the following operations:
@@ -37,7 +38,7 @@ the *domain admin*, and Orchestration uses that user to manage the
 lifecycle of the users in the stack *user domain*.
 
 Stack domain users configuration
---------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To configure stack domain users the following steps shall be executed:
 
@@ -102,7 +103,7 @@ You must complete the following steps to setup stack domain users:
        stack_user_domain = domain id returned from domain create above
 
 Usage workflow
---------------
+~~~~~~~~~~~~~~
 
 The following steps will be executed during stack creation:
 

doc/admin-guide-cloud-rst/source/orchestration.rst

@@ -12,45 +12,10 @@ also endeavors to provide compatibility with the AWS CloudFormation
 template format, so that many existing CloudFormation templates can
 be launched on OpenStack.
 
-Introduction
-~~~~~~~~~~~~
-
-Orchestration is a tool for orchestrating clouds that automatically
-configures and deploys resources in stacks. Such deployments can be
-simple — like deploying WordPress on Ubuntu with an SQL back end.
-And they can be quite complex, like launching a group of servers that
-autoscale: starting and stopping based on realtime CPU loading
-information from the Telemetry module.
-
-Orchestration stacks are defined with templates, which are
-non-procedural documents describing tasks in terms of resources,
-parameters, inputs, constraints and dependencies. When Orchestration
-module was originally introduced, it worked with AWS CloudFormation
-templates, which are in JSON format.
-
-Now, Orchestration also executes HOT (Heat Orchestration Template)
-templates written in YAML: a terse notation that loosely follows
-Python/Ruby-type structural conventions (colons, returns,
-indentation), so it is more easy to write, parse, grep, generate with
-tools, and maintain source-code management systems.
-
-Orchestration can be accessed via the CLI, and using RESTful queries.
-Orchestration module provides both an OpenStack-native REST API and a
-CloudFormation-compatible Query API. Orchestration is also integrated
-with OpenStack dashboard in order to launch stacks from templates
-through a web interface.
-
-For more details on how to use Orchestration module through a command
-line, see `OpenStack Command-Line Interface Reference`_.
-
-.. Links
-.. _`OpenStack Command-Line Interface Reference`: http://docs.openstack.org/cli-reference
-
-.. include:: orchestration-auth-model.rst
-.. include:: orchestration-stack-domain-users.rst
-
 .. toctree::
-   :hidden:
 
+   orchestration-introduction.rst
    orchestration-auth-model.rst
    orchestration-stack-domain-users.rst
+
+