Update plugin documentation

2 files changed, 19 insertions, 3 deletions

diff --git a/buildstream/buildelement.py b/buildstream/buildelement.py
index 6d6c200ca..cf4d6136b 100644
--- a/buildstream/buildelement.py
+++ b/buildstream/buildelement.py
@@ -55,6 +55,15 @@ will do the following operations:
   :func:`Element.stage_sources() <buildstream.element.Element.integrate>`
 
 
+Element.prepare()
+~~~~~~~~~~~~~~~~~
+
+In :func:`Element.prepare() <buildstream.element.Element.prepare>`,
+the BuildElement will run ``configure-commands``, which are used to
+run one-off preparations that should not be repeated for a single
+build directory.
+
+
 Element.assemble()
 ~~~~~~~~~~~~~~~~~~
 In :func:`Element.assemble() <buildstream.element.Element.assemble>`, the
@@ -63,7 +72,6 @@ found in the element configuration.
 
 Commands are run in the following order:
 
-* ``configure-commands``: Commands to configure how the element will build
 * ``build-commands``: Commands to build the element
 * ``install-commands``: Commands to install the results into ``%{install-root}``
 * ``strip-commands``: Commands to strip debugging symbols installed binaries
diff --git a/buildstream/element.py b/buildstream/element.py
index 5df21bf72..b7af56248 100644
--- a/buildstream/element.py
+++ b/buildstream/element.py
@@ -35,8 +35,9 @@ For loading and configuration purposes, Elements must implement the
 
 Build Phase
 ~~~~~~~~~~~
-The following methods are the foundation of the element's *build phase*, they
-must be implemented by all Element classes.
+The following methods are the foundation of the element's *build
+phase*, they must be implemented by all Element classes, unless
+explicitly stated otherwise.
 
 * :func:`Element.configure_sandbox() <buildstream.element.Element.configure_sandbox>`
 
@@ -47,6 +48,13 @@ must be implemented by all Element classes.
   Stage dependencies and :class:`Sources <buildstream.source.Source>` into
   the sandbox.
 
+* :func:`Element.prepare() <buildstream.element.Element.prepare>`
+
+  Call preparation methods that should only be performed once in the
+  lifetime of a build directory (e.g. autotools' ./configure).
+
+  **Optional**: If left unimplemented, this step will be skipped.
+
 * :func:`Element.assemble() <buildstream.element.Element.assemble>`
 
   Perform the actual assembly of the element