Add documentation

5 files changed, 70 insertions, 1 deletions

diff --git a/buildstream/plugin.py b/buildstream/plugin.py
index 110d865f5..5be2255e5 100644
--- a/buildstream/plugin.py
+++ b/buildstream/plugin.py
@@ -19,7 +19,52 @@
 #        Tristan Van Berkom <tristan.vanberkom@codethink.co.uk>
 """
 Plugin
-======
+=======
+BuildStream supports third party plugins to define additional kinds of
+elements and sources.
+
+Plugin Structure
+----------------
+A plugin should consist of a `setuptools package
+<http://setuptools.readthedocs.io/en/latest/setuptools.html>`_ that
+advertises contained plugins using `entry points
+<http://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins>`_.
+
+A plugin entry point must be a module that extends a class in the
+:ref:`core_framework` to be discovered by BuildStream. A YAML file
+defining plugin default settings with the same name as the module can
+also be defined in the same directory as the plugin module.
+
+.. note::
+
+    BuildStream does not support function/class entry points.
+
+A sample plugin could be structured as such:
+
+.. code-block:: text
+
+    .
+    ├── elements
+    │   ├── autotools.py
+    │   ├── autotools.yaml
+    │   └── __init__.py
+    ├── MANIFEST.in
+    └── setup.py
+
+The setuptools configuration should then contain at least:
+
+setup.py:
+
+.. literalinclude:: ../source/sample_plugin/setup.py
+   :language: python
+
+MANIFEST.in:
+
+.. literalinclude:: ../source/sample_plugin/setup.py
+   :language: text
+
+Class Reference
+---------------
 """
 
 import os
@@ -44,6 +89,7 @@ class Plugin():
 
     Some common features to both Sources and Elements are found
     in this class.
+
     """
 
     BST_REQUIRED_VERSION_MAJOR = 0
diff --git a/doc/source/format.rst b/doc/source/format.rst
index ebe8e2636..6be1893f9 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -152,6 +152,12 @@ The ``kind`` attribute specifies which plugin will be operating on the element's
 produce its output. Plugins define element types and each of them can be referred to by
 name with the ``kind`` attribute.
 
+To refer to a third party plugin, prefix the plugin with its package, for example:
+
+.. code:: yaml
+
+   kind: buildstream-plugins:dpkg_build
+
 
 Depends
 ~~~~~~~
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 5a06b501d..1d9477740 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -79,6 +79,7 @@ The following source types are provided with BuildStream:
 * :mod:`ostree <sources.ostree>` - A Source implementation for ostree
 * :mod:`patch <sources.patch>` - A Source implementation for applying local patches
 
+.. _core_framework:
 
 Core Framework
 --------------
diff --git a/doc/source/sample_plugin/MANIFEST.in b/doc/source/sample_plugin/MANIFEST.in
new file mode 100644
index 000000000..2be67bf4e
--- /dev/null
+++ b/doc/source/sample_plugin/MANIFEST.in
@@ -0,0 +1 @@
+global-include *.yaml
diff --git a/doc/source/sample_plugin/setup.py b/doc/source/sample_plugin/setup.py
new file mode 100644
index 000000000..7ea0e1ef3
--- /dev/null
+++ b/doc/source/sample_plugin/setup.py
@@ -0,0 +1,15 @@
+from setuptools import setup, find_packages
+
+setup(name='BuildStream Autotools',
+      version="0.1",
+      description="A better autotools element for BuildStream",
+      packages=find_packages(),
+      install_requires=[
+          'setuptools'
+      ],
+      include_package_data=True,
+      entry_points={
+          'buildstream.plugins': [
+              'autotools = elements.autotools'
+          ]
+      })