Aim first doc link list at end users

This change renames the first doc link section Getting Started to
Using Heat and makes the content relevant to end users of Heat.

End users author templates, create stacks, and use the heat CLI.
They are not necessarily interested in installing heat from packages or
devstack.

This change breaks out the basic create-stack content into its own page
and links to that from the first Using Heat contents list. The rest of
the getting started content is moved to the Developers section for now,
pending later changes aimed at developers and operators.

Change-Id: I79988e08864c5a87ebc4f8f5a39102d50b26f748

5 files changed, 129 insertions, 98 deletions

diff --git a/doc/source/getting_started/create_a_stack.rst b/doc/source/getting_started/create_a_stack.rst
new file mode 100644
index 000000000..08e0f49da
--- /dev/null
+++ b/doc/source/getting_started/create_a_stack.rst
@@ -0,0 +1,107 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _create-a-stack:
+
+Creating your first stack
+=========================
+
+Confirming you can access a Heat endpoint
+-----------------------------------------
+
+Before any Heat commands can be run, your cloud credentials need to be
+sourced::
+
+    $ source openrc
+
+You can confirm that Heat is available with this command::
+
+    $ heat stack-list
+
+This should return an empty line
+
+Preparing to create a stack
+---------------------------
+
+Your cloud will have different flavors and images available for
+launching instances, you can discover what is available by running::
+
+    $ openstack flavor list
+    $ openstack image list
+
+
+To allow you to SSH into instances launched by Heat, a keypair will be
+generated::
+
+    $ openstack keypair create heat_key > heat_key.priv
+    $ chmod 600 heat_key.priv
+
+Launching a stack
+-----------------
+Now lets launch a stack, using an example template from the heat-templates repository::
+
+    $ heat stack-create -u http://git.openstack.org/cgit/openstack/heat-templates/plain/hot/F20/WordPress_Native.yaml -P key_name=heat_key -P image_id=my-fedora-image -P instance_type=m1.small teststack
+
+Which will respond::
+
+    +--------------------------------------+-----------+--------------------+----------------------+
+    | ID                                   | Name      | Status             | Created              |
+    +--------------------------------------+-----------+--------------------+----------------------+
+    | (uuid)                               | teststack | CREATE_IN_PROGRESS | (timestamp)          |
+    +--------------------------------------+-----------+--------------------+----------------------+
+
+List stacks
+~~~~~~~~~~~
+List the stacks in your tenant::
+
+    $ heat stack-list
+
+List stack events
+~~~~~~~~~~~~~~~~~
+List the events related to a particular stack::
+
+   $ heat event-list teststack
+
+Describe the wordpress stack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Show detailed state of a stack::
+
+   $ heat stack-show teststack
+
+Note: After a few seconds, the stack_status should change from ``IN_PROGRESS``
+to ``CREATE_COMPLETE``.
+
+Verify instance creation
+~~~~~~~~~~~~~~~~~~~~~~~~
+Because the software takes some time to install from the repository, it may be
+a few minutes before the Wordpress instance is in a running state.
+
+Point a web browser at the location given by the ``WebsiteURL`` output as shown
+by ``heat output-show``::
+
+    $ WebsiteURL=$(heat output-show --format raw teststack WebsiteURL)
+    $ curl $WebsiteURL
+
+Delete the instance when done
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Note: The list operation will show no running stack.::
+
+    $ heat stack-delete teststack
+    $ heat stack-list
+
+You can explore other heat commands by refering to the
+`Heat chapter
+<http://docs.openstack.org/cli-reference/content/heatclient_commands.html>`_
+of the `OpenStack Command-Line Interface Reference
+<http://docs.openstack.org/cli-reference/content/index.html>`_ then read
+the :ref:`template-guide` and start authoring your own templates.
diff --git a/doc/source/getting_started/on_devstack.rst b/doc/source/getting_started/on_devstack.rst
index 1e37cf394..b6d36b88b 100644
--- a/doc/source/getting_started/on_devstack.rst
+++ b/doc/source/getting_started/on_devstack.rst
@@ -74,87 +74,8 @@ Get pretty HTML with traces::
 
 Note that osprofiler should be run with the admin user name & tenant.
 
+Create a stack
+--------------
 
-Confirming Heat is responding
------------------------------
-
-Before any Heat commands can be run, the authentication environment
-needs to be loaded::
-
-    source openrc
-
-You can confirm that Heat is running and responding
-with this command::
-
-    heat stack-list
-
-This should return an empty line
-
-Preparing Nova for running stacks
----------------------------------
-
-Enabling Heat in devstack will replace the default Nova flavors with
-flavors that the Heat example templates expect. You can see what
-those flavors are by running::
-
-    nova flavor-list
-
-Heat needs to launch instances with a keypair, so we need
-to generate one::
-
-    nova keypair-add heat_key > heat_key.priv
-    chmod 600 heat_key.priv
-
-Launching a stack
------------------
-Now lets launch a stack, using an example template from the heat-templates repository::
-
-    heat stack-create teststack -u
-    http://git.openstack.org/cgit/openstack/heat-templates/plain/hot/F20/WordPress_Native.yaml -P key_name=heat_key -P image_id=Fedora-x86_64-20-20131211.1-sda
-
-Which will respond::
-
-    +--------------------------------------+-----------+--------------------+----------------------+
-    | ID                                   | Name      | Status             | Created              |
-    +--------------------------------------+-----------+--------------------+----------------------+
-    | (uuid)                               | teststack | CREATE_IN_PROGRESS | (timestamp)          |
-    +--------------------------------------+-----------+--------------------+----------------------+
-
-
-List stacks
-~~~~~~~~~~~
-List the stacks in your tenant::
-
-    heat stack-list
-
-List stack events
-~~~~~~~~~~~~~~~~~
-
-List the events related to a particular stack::
-
-   heat event-list teststack
-
-Describe the wordpress stack
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Show detailed state of a stack::
-
-   heat stack-show teststack
-
-Note: After a few seconds, the stack_status should change from IN_PROGRESS to CREATE_COMPLETE.
-
-Verify instance creation
-~~~~~~~~~~~~~~~~~~~~~~~~
-Because the software takes some time to install from the repository, it may be a few minutes before the Wordpress instance is in a running state.
-
-Point a web browser at the location given by the WebsiteURL Output as shown by heat stack-show teststack::
-
-    wget ${WebsiteURL}
-
-Delete the instance when done
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Note: The list operation will show no running stack.::
-
-    heat stack-delete teststack
-    heat stack-list
+Now that you have a working Heat environment you can go to
+:ref:`create-a-stack`.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9e0f70b18..569e5a48e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -43,15 +43,15 @@ Heat's purpose and vision
 This documentation offers information aimed at end-users, operators and
 developers of Heat.
 
-Getting Started
-===============
+Using Heat
+==========
 
 .. toctree::
     :maxdepth: 1
 
-    getting_started/index
-    templates/index
+    getting_started/create_a_stack
     template_guide/index
+    templates/index
     glossary
 
 Man Pages
@@ -65,13 +65,14 @@ Man Pages
 Developers Documentation
 ========================
 .. toctree::
-   :maxdepth: 1
+    :maxdepth: 1
 
-   architecture
-   pluginguide
-   schedulerhints
-   gmr
-   supportstatus
+    getting_started/index
+    architecture
+    pluginguide
+    schedulerhints
+    gmr
+    supportstatus
 
 API Documentation
 ========================
diff --git a/doc/source/template_guide/index.rst b/doc/source/template_guide/index.rst
index 6001ca2c4..76996f03a 100644
--- a/doc/source/template_guide/index.rst
+++ b/doc/source/template_guide/index.rst
@@ -11,6 +11,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _template-guide:
+
 Template Guide
 ==============
 
@@ -31,4 +33,4 @@ Template Guide
    functions
 
 .. existing_templates
-.. advanced_topics
\ No newline at end of file
+.. advanced_topics
diff --git a/doc/source/templates/index.rst b/doc/source/templates/index.rst
index 9915b3349..b482fd4de 100644
--- a/doc/source/templates/index.rst
+++ b/doc/source/templates/index.rst
@@ -13,16 +13,16 @@
 
 This page documents the templates at https://github.com/openstack/heat-templates/
 
-HOT Templates
-=============
+Example HOT Templates
+=====================
 
 .. toctree::
   :maxdepth: 1
 
   hot/hello_world
 
-CFN Templates
-=============
+Example CFN Templates
+=====================
 
 .. toctree::
   :maxdepth: 1