Merge "Re-organize the Wacher documentation Home Page"

doc/source/deploy/user-guide.rst

@@ -6,9 +6,9 @@
 
 .. _user-guide:
 
-=================================
+==================
-Welcome to the Watcher User Guide
+Watcher User Guide
-=================================
+==================
 
 See the
 `architecture page <https://factory.b-com.com/www/watcher/doc/watcher/architecture.html>`_
@@ -29,7 +29,7 @@ Getting started with Watcher
 ----------------------------
 This guide assumes you have a working installation of Watcher. If you get
 "*watcher: command not found*" you may have to verify your installation.
-Please refer to the :doc:`installation guide <installation>`.
+Please refer to the `installation guide`_.
 In order to use Watcher, you have to configure your credentials suitable for
 watcher command-line tools.
 If you need help on a specific command, you can use:
@@ -38,6 +38,8 @@ If you need help on a specific command, you can use:
 
   $ watcher help COMMAND
 
+.. _`installation guide`: https://factory.b-com.com/www/watcher/doc/python-watcherclient
+
 Seeing what the Watcher CLI can do ?
 ------------------------------------
 We can see all of the commands available with Watcher CLI by running the

doc/source/dev/devstack.rst

@@ -1,6 +1,12 @@
-===============
+..
-DevStack Plugin
+      Except where otherwise noted, this document is licensed under Creative
-===============
+      Commons Attribution 3.0 License.  You can view the license at:
+
+          https://creativecommons.org/licenses/by/3.0/
+
+=============================================
+Set up a development environment via DevStack
+=============================================
 
 Watcher is currently able to optimize compute resources - specifically Nova
 compute hosts - via operations such as live migrations.  In order for you to

doc/source/dev/environment.rst

@@ -4,9 +4,9 @@
 
           https://creativecommons.org/licenses/by/3.0/
 
-============================================
+=========================================
-Setting up a Watcher development environment
+Set up a development environment manually
-============================================
+=========================================
 
 This document describes getting the source from watcher `Git repository`_
 for development purposes.

doc/source/dev/strategy-plugin.rst

@@ -4,22 +4,20 @@
 
           https://creativecommons.org/licenses/by/3.0/
 
-===============
+=================================
-Watcher plugins
+Build a new optimization strategy
-===============
+=================================
 
-Writing a Watcher Decision Engine plugin
+Watcher Decision Engine has an external :ref:`strategy <strategy_definition>`
-========================================
+plugin interface which gives anyone the ability to integrate an external
-
+:ref:`strategy <strategy_definition>` in order to make use of placement
-Watcher has an external :ref:`strategy <strategy_definition>` plugin interface
+algorithms.
-which gives anyone the ability to integrate an external :ref:`strategy
-<strategy_definition>` in order to make use of placement algorithms.
 
 This section gives some guidelines on how to implement and integrate custom
 Stategies with Watcher.
 
 Pre-requisites
---------------
+==============
 
 Before using any strategy, you should make sure you have your Telemetry service
 configured so that it would provide you all the metrics you need to be able to
@@ -27,7 +25,7 @@ use your strategy.
 
 
 Creating a new plugin
----------------------
+=====================
 
 First of all you have to:
 
@@ -65,7 +63,7 @@ your ``__init__`` method.
 
 
 Abstract Plugin Class
----------------------
+=====================
 
 Here below is the abstract ``BaseStrategy`` class that every single strategy
 should implement:
@@ -79,7 +77,7 @@ should implement:
 
 
 Add a new entry point
----------------------
+=====================
 
 In order for the Watcher Decision Engine to load your new strategy, the
 strategy must be registered as a named entry point under the
@@ -103,7 +101,7 @@ have a look at the :py:class:`BasicConsolidation` class.
 .. _pbr: http://docs.openstack.org/developer/pbr/
 
 Using strategy plugins
-----------------------
+======================
 
 The Watcher Decision Engine service will automatically discover any installed
 plugins when it is run. If a Python package containing a custom plugin is
@@ -128,7 +126,7 @@ Telemetry service. In such a case, please do make sure that you first
 check/configure the latter so your new strategy can be fully functional.
 
 Querying metrics
-~~~~~~~~~~~~~~~~
+----------------
 
 The metrics available depend on the hypervisors that OpenStack manages on
 the specific implementation. You can find the metrics available per hypervisor
@@ -139,7 +137,7 @@ use the default Ceilometer API or our Helper.
 The Helper attempted to make the Ceilometer API more reusable and easy to use.
 
 Read usage metrics using the Python binding
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
 
 You can find the information about the Ceilometer Python binding on the
 OpenStack `ceilometer client python API documentation
@@ -161,7 +159,7 @@ Using that you can now query the values for that specific metric:
  value_cpu = cclient.samples.list(meter_name='cpu_util', limit=10, q=query)
 
 Read usage metrics using the Watcher Cluster History Helper
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------------------
 
 Here below is the abstract ``BaseClusterHistory`` class of the Helper.
 

doc/source/index.rst

@@ -4,16 +4,32 @@
 
           https://creativecommons.org/licenses/by/3.0/
 
-============================================
+================================
-Welcome to Watcher's developer documentation
+Welcome to Watcher documentation
-============================================
+================================
 
-.. include:: ../../README.rst
+OpenStack Watcher provides a flexible and scalable resource optimization
+service for multi-tenant OpenStack-based clouds.
+Watcher provides a complete optimization loop—including everything from a
+metrics receiver, complex event processor and profiler, optimization processor
+and an action plan applier. This provides a robust framework to realize a wide
+range of cloud optimization goals, including the reduction of data center
+operating costs, increased system performance via intelligent virtual machine
+migration, increased energy efficiency—and more!
 
-The developer documentation provided here is continually kept up-to-date based
+Watcher project consists of several source code repositories:
+
+* `watcher`_ - is the main repository. It contains code for Watcher API server,
+  Watcher Decision Engine and Watcher Applier.
+* `python-watcherclient`_ - Client library and CLI client for Watcher.
+
+The documentation provided here is continually kept up-to-date based
 on the latest code, and may not represent the state of the project at any
 specific prior release.
 
+.. _watcher: https://git.openstack.org/cgit/openstack/watcher/
+.. _python-watcherclient: https://git.openstack.org/cgit/openstack/python-watcherclient/
+
 Developer Guide
 ===============
 
@@ -25,22 +41,19 @@ Introduction
 
   glossary
   architecture
-  deploy/configuration
-  dev/environment
   dev/contributing
-  dev/plugins
 
 
-DevStack Plugin
+Getting Started
 ---------------
 
-You can configure DevStack to set up the Watcher services easily using
-Watcher's DevStack plugin.
-
 .. toctree::
   :maxdepth: 1
 
-  dev/devstack-plugin
+  dev/environment
+  dev/devstack
+  deploy/configuration
+
 
 API References
 --------------
@@ -50,17 +63,26 @@ API References
 
   webapi/v1
 
-Admin Guide
+Plugins
-===========
+-------
-
+
-Overview
+.. toctree::
---------
+  :maxdepth: 1
+
+  dev/strategy-plugin
+
+
+Admin Guide
+===========
+
+Introduction
+------------
 
 .. toctree::
   :maxdepth: 1
 
-  deploy/user-guide
   deploy/installation
+  deploy/user-guide
 
 Watcher Manual Pages
 ====================