From 63d950090414b46bdcfbe81db72763b935579845 Mon Sep 17 00:00:00 2001 From: David TARDIVEL Date: Fri, 15 Jan 2016 15:39:50 +0100 Subject: [PATCH] Re-organize the Wacher documentation Home Page Change the title of the page. Create a 'Getting Started' section. Create a 'Plugins' section. Add links to related source code repositories. Fix bad link to watcher client installation doc. Change-Id: Ie0548149751d53b5fca235da69798dd0d333b14c Partial-Bug: #1535244 --- doc/source/deploy/user-guide.rst | 10 ++-- .../dev/{devstack-plugin.rst => devstack.rst} | 12 +++- doc/source/dev/environment.rst | 6 +- .../dev/{plugins.rst => strategy-plugin.rst} | 32 +++++----- doc/source/index.rst | 60 +++++++++++++------ 5 files changed, 74 insertions(+), 46 deletions(-) rename doc/source/dev/{devstack-plugin.rst => devstack.rst} (93%) rename doc/source/dev/{plugins.rst => strategy-plugin.rst} (90%) diff --git a/doc/source/deploy/user-guide.rst b/doc/source/deploy/user-guide.rst index 9c7d7ec57..db0b23cce 100644 --- a/doc/source/deploy/user-guide.rst +++ b/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 `_ @@ -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 `. +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 diff --git a/doc/source/dev/devstack-plugin.rst b/doc/source/dev/devstack.rst similarity index 93% rename from doc/source/dev/devstack-plugin.rst rename to doc/source/dev/devstack.rst index aa8276efe..4135a6e22 100644 --- a/doc/source/dev/devstack-plugin.rst +++ b/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 diff --git a/doc/source/dev/environment.rst b/doc/source/dev/environment.rst index 0a64c28a6..820c12d7a 100644 --- a/doc/source/dev/environment.rst +++ b/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. diff --git a/doc/source/dev/plugins.rst b/doc/source/dev/strategy-plugin.rst similarity index 90% rename from doc/source/dev/plugins.rst rename to doc/source/dev/strategy-plugin.rst index ad82dcd95..d91014e36 100644 --- a/doc/source/dev/plugins.rst +++ b/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 has an external :ref:`strategy ` plugin interface -which gives anyone the ability to integrate an external :ref:`strategy -` in order to make use of placement algorithms. +Watcher Decision Engine has an external :ref:`strategy ` +plugin interface which gives anyone the ability to integrate an external +:ref:`strategy ` 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 6e2bc06b8..13e3f173f 100644 --- a/doc/source/index.rst +++ b/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 -=========== - -Overview --------- +Plugins +------- + +.. toctree:: + :maxdepth: 1 + + dev/strategy-plugin + + +Admin Guide +=========== + +Introduction +------------ .. toctree:: :maxdepth: 1 - deploy/user-guide deploy/installation + deploy/user-guide Watcher Manual Pages ====================