feat(docs): scons plugin reference (#714)

Signed-off-by: Sergio Schvezov <[email protected]>
Co-authored-by: Alex Lowe <[email protected]>
Co-authored-by: Tiago Nobrega <[email protected]>

docs/common/craft-parts/reference/plugins/scons_plugin.rst

@@ -0,0 +1,78 @@
+.. _craft_parts_scons_plugin:
+
+SCons plugin
+============
+
+The SCons plugin builds projects using SCons_.
+
+After a successful build, this plugin will install the generated
+binaries in ``$CRAFT_PART_INSTALL``.
+
+Keywords
+--------
+
+In addition to the common :ref:`plugin <part-properties-plugin>` and
+:ref:`sources <part-properties-sources>` keywords, this plugin provides the following
+plugin-specific keywords:
+
+scons-parameters
+~~~~~~~~~~~~~~~~
+**Type:** list of strings
+**Default:** []
+
+Parameters to pass to SCons for building and installation.
+
+Environment variables
+---------------------
+
+This plugin sets ``DESTDIR`` to ``$CRAFT_PART_INSTALL``.
+
+Dependencies
+------------
+
+The SCons plugin needs the ``scons`` executable to build, but does not
+provision it by itself.
+
+The common means of providing ``scons`` is through a
+:ref:`build-packages <build_packages>` entry which for Ubuntu, would be ``scons``.
+
+Another alternative is to define another part with the name ``scons-deps``, and
+declare that the part using the ``scons`` plugin comes :ref:`after <after>` the
+``scons-deps`` part. In this case, the plugin will assume that this new part will
+provide the ``scons`` executable to be used in the build step. This can be useful,
+for example, in cases where a specific, unreleased version of ``scons`` is desired
+but only possible by either building the tool itself from source or through some
+other custom mechanism.
+
+
+How it works
+------------
+
+During the build step the plugin performs the following actions:
+
+* Run ``scons`` with any ``scons-parameters`` that might have been set;
+* Run ``scons install`` with any ``scons-parameters`` that might have been set,
+  the ``DESTDIR`` environment variable would affect the final installation path.
+
+Examples
+--------
+
+The following snippet declares a part using the ``scons`` plugin. It
+sets the ``scons-parameters`` for a ``prefix`` to be set to
+``/usr``. To ``scons`` executable dependency is satisfied with
+:ref:`build-packages <build_packages>`:
+
+.. code-block:: yaml
+
+    parts:
+      gpsd:
+        source: .
+        plugin: scons
+        scons-parameters:
+          - prefix=/usr
+        build-packages:
+          - scons
+
+
+.. _SCons: https://scons.org/
+

docs/reference/plugins.rst

@@ -19,6 +19,7 @@ lifecycle.
    /common/craft-parts/reference/plugins/nil_plugin.rst
    /common/craft-parts/reference/plugins/python_plugin.rst
    /common/craft-parts/reference/plugins/rust_plugin.rst
+   /common/craft-parts/reference/plugins/scons_plugin.rst
 
 
 When documenting a new plugin, follow the guidelines in :ref:`how_to_document_a_plugin`.