From de7b0129a1f7ccc8d4b7a1724535c4a2d2e55c8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vincent=20Fran=C3=A7oise?= <Vincent.FRANCOISE@b-com.com>
Date: Mon, 22 Feb 2016 15:32:29 +0100
Subject: [PATCH] Doc on how to set up a thirdparty project

This documentation is a pre-requisite to all plugin documentation
as it guides you through the creation of a project from scratch
instead of simply forcusing on the implementation of the plugin
itself.

Change-Id: Id2e09b3667390ee6c4be42454c41f9d266fdfac2
Related-Bug: #1534639
Related-Bug: #1533739
Related-Bug: #1533740
---
 doc/source/dev/environment.rst            |  2 +
 doc/source/dev/plugin/base-setup.rst      | 90 +++++++++++++++++++++++
 doc/source/dev/plugin/strategy-plugin.rst |  2 -
 doc/source/index.rst                      |  1 +
 4 files changed, 93 insertions(+), 2 deletions(-)
 create mode 100644 doc/source/dev/plugin/base-setup.rst

diff --git a/doc/source/dev/environment.rst b/doc/source/dev/environment.rst
index 41db0b6f8..6ed0218b4 100644
--- a/doc/source/dev/environment.rst
+++ b/doc/source/dev/environment.rst
@@ -4,6 +4,8 @@
 
           https://creativecommons.org/licenses/by/3.0/
 
+.. _watcher_developement_environment:
+
 =========================================
 Set up a development environment manually
 =========================================
diff --git a/doc/source/dev/plugin/base-setup.rst b/doc/source/dev/plugin/base-setup.rst
new file mode 100644
index 000000000..1cac69d76
--- /dev/null
+++ b/doc/source/dev/plugin/base-setup.rst
@@ -0,0 +1,90 @@
+..
+      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/
+
+.. _plugin-base_setup:
+
+=======================================
+Create a third-party plugin for Watcher
+=======================================
+
+Watcher provides a plugin architecture which allows anyone to extend the
+existing functionalities by implementing third-party plugins. This process can
+be cumbersome so this documentation is there to help you get going as quickly
+as possible.
+
+
+Pre-requisites
+==============
+
+We assume that you have set up a working Watcher development environment. So if
+this not already the case, you can check out our documentation which explains
+how to set up a :ref:`development environment
+<watcher_developement_environment>`.
+
+.. _development environment:
+
+Third party project scaffolding
+===============================
+
+First off, we need to create the project structure. To do so, we can use
+`cookiecutter`_ and the `OpenStack cookiecutter`_ project scaffolder to
+generate the skeleton of our project::
+
+    $ virtualenv thirdparty
+    $ source thirdparty/bin/activate
+    $ pip install cookiecutter
+    $ cookiecutter https://github.com/openstack-dev/cookiecutter
+
+The last command will ask you for many information, and If you set
+``module_name`` and ``repo_name`` as ``thirdparty``, you should end up with a
+structure that looks like this::
+
+    $ cd thirdparty
+    $ tree .
+    .
+    ├── babel.cfg
+    ├── CONTRIBUTING.rst
+    ├── doc
+    │   └── source
+    │       ├── conf.py
+    │       ├── contributing.rst
+    │       ├── index.rst
+    │       ├── installation.rst
+    │       ├── readme.rst
+    │       └── usage.rst
+    ├── HACKING.rst
+    ├── LICENSE
+    ├── MANIFEST.in
+    ├── README.rst
+    ├── requirements.txt
+    ├── setup.cfg
+    ├── setup.py
+    ├── test-requirements.txt
+    ├── thirdparty
+    │   ├── __init__.py
+    │   └── tests
+    │       ├── base.py
+    │       ├── __init__.py
+    │       └── test_thirdparty.py
+    └── tox.ini
+
+.. _cookiecutter: https://github.com/audreyr/cookiecutter
+.. _OpenStack cookiecutter: https://github.com/openstack-dev/cookiecutter
+
+Implementing a plugin for Watcher
+=================================
+
+Now that the project skeleton has been created, you can start the
+implementation of your plugin. As of now, you can implement the following
+plugins for Watcher:
+
+- A :ref:`strategy plugin <implement_strategy_plugin>`
+- A :ref:`planner plugin <implement_planner_plugin>`
+- An :ref:`action plugin <implement_strategy_plugin>`
+- A :ref:`workflow engine plugin <implement_workflow_engine_plugin>`
+
+If you want to learn more on how to implement them, you can refer to their
+dedicated documentation.
diff --git a/doc/source/dev/plugin/strategy-plugin.rst b/doc/source/dev/plugin/strategy-plugin.rst
index a660f92aa..a83b5b78b 100644
--- a/doc/source/dev/plugin/strategy-plugin.rst
+++ b/doc/source/dev/plugin/strategy-plugin.rst
@@ -38,8 +38,6 @@ Here is an example showing how you can write a plugin called ``DummyStrategy``:
 
 .. code-block:: python
 
-    # Filepath = third-party/thirdparty/dummy.py
-    # Import path = thirdparty.dummy
     import uuid
 
     class DummyStrategy(BaseStrategy):
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4a8819564..95168d32c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -72,6 +72,7 @@ Plugins
 .. toctree::
   :maxdepth: 1
 
+  dev/plugin/base-setup
   dev/plugin/strategy-plugin
   dev/plugin/action-plugin
   dev/plugin/planner-plugin