Added documentation about public data in the bst domain.

3 files changed, 78 insertions, 0 deletions

diff --git a/doc/source/format.rst b/doc/source/format.rst
index 775a725ca..ef4b2cb5b 100644
--- a/doc/source/format.rst
+++ b/doc/source/format.rst
@@ -265,6 +265,8 @@ For meaningful documentation on what can be specified in the ``config`` section
 element ``kind``, refer to the element specific documentation. 
 
 
+.. _format_public:
+
 Public
 ~~~~~~
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9e8f0c66f..d42848d0c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -34,6 +34,7 @@ off the ground installing it on a new host.
 * :ref:`config`
 * :ref:`projectconf`
 * :ref:`format`
+* :ref:`public`
 
 
 Elements
@@ -83,6 +84,7 @@ implement custom :mod:`Element <buildstream.element>` or
 * :mod:`Source <buildstream.source>` - Base Source Class
 * :mod:`Element <buildstream.element>` - Base Element Class
 * :mod:`BuildElement <buildstream.buildelement>` - Build Element Class
+* :mod:`ScriptElement <buildstream.scriptelement>` - Script Element Class
 * :mod:`Context <buildstream.context>` - Invocation Context
 * :mod:`Project <buildstream.project>` - Loaded Project
 * :mod:`Sandbox <buildstream.sandbox>` - Build Sandbox
diff --git a/doc/source/public.rst b/doc/source/public.rst
new file mode 100644
index 000000000..7bedfaafa
--- /dev/null
+++ b/doc/source/public.rst
@@ -0,0 +1,74 @@
+.. _public:
+
+
+Public Data
+===========
+
+Elements can provide public data which can be read by other elements
+later in the pipeline, the format for exposing public data on a given
+element is :ref:`described here <format_public>`.
+
+Any element may use public data for whatever purpose it wants, but
+BuildStream has some built-in expectations of public data, which resides
+completely in the ``bst`` domain.
+
+In this section we will describe the public data in the ``bst`` domain.
+
+
+Integration Commands
+--------------------
+
+.. code:: yaml
+
+   # Specify some integration commands
+   public:
+     bst:
+       integration-commands:
+       - /usr/bin/update-fancy-feature-cache
+
+The built-in ``integration-commands`` list indicates that depending elements
+should run this set of commands before expecting the staged runtime environment
+to be functional.
+
+Typical cases for this include running ``ldconfig`` at the base of a pipeline,
+or running commands to update various system caches.
+
+Integration commands of a given element are automatically run by the
+:func:`Element.integrate() <buildstream.element.Element.integrate>` method
+and are used by various plugins.
+
+Notably the :mod:`BuildElement <buildstream.buildelement>` derived classes
+will always integrate the build dependencies after staging and before running
+any build commands.
+
+
+Split Rules
+-----------
+
+.. code:: yaml
+
+   # Specify some split rules
+   public:
+     bst:
+       split-rules:
+         runtime:
+         - |
+           %{bindir}/*
+         - |
+           %{sbindir}/*
+         - |
+           %{libexecdir}/*
+         - |
+           %{libdir}/lib*.so*
+
+Split rules indicate how the output of an element can be categorized
+into *domains*.
+
+The ``split-rules`` domains are used by the
+:func:`Element.stage_artifact() <buildstream.element.Element.stage_artifact>`
+method when deciding what domains of an artifact should be staged.
+
+This is used for creating compositions with the
+:mod:`compose <elements.compose>` element and can be used by other deployment
+related elements for the purpose of splitting element artifacts into separate
+packages.