Merge branch 'chandan/bst-and-docker' into 'master'

Add documentation and NEWS entry about bst-docker-import

See merge request !864

NEWS

@@ -24,6 +24,9 @@ buildstream 1.3.1
   o Add new `pip` source plugin for downloading python packages using pip,
     based on requirements files from previous sources.
 
+  o Generate Docker images from built artifacts using
+    `contrib/bst-docker-import` script.
+
 
 =================
 buildstream 1.1.5

doc/source/additional_docker.rst

+
+.. _bst_and_docker:
+
+
+BuildStream and Docker
+======================
+
+BuildStream integrates with Docker in multiple ways. Here are some ways in
+which these integrations work.
+
+Run BuildStream inside Docker
+-----------------------------
+
+Refer to the :ref:`BuildStream inside Docker <docker>` documentation for
+instructions on how to run BuildStream as a Docker container.
+
+Generate Docker images
+----------------------
+
+The
+`bst-docker-import script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-docker-import>`_
+can be used to generate a Docker image from built artifacts.
+
+You can download it and make it executable like this:
+
+.. code:: bash
+
+  mkdir -p ~/.local/bin
+  curl --get https://gitlab.com/BuildStream/buildstream/raw/master/contrib/bst-docker-import > ~/.local/bin/bst-docker-import
+  chmod +x ~/.local/bin/bst-docker-import
+
+Check if ``~/.local/bin`` appears in your PATH environment variable -- if it
+doesn't, you should
+`edit your ~/.profile so that it does <https://stackoverflow.com/questions/14637979/>`_.
+
+Once the script is available in your PATH and assuming you have Docker
+installed, you can start using the ``bst-docker-import`` script. Here is a
+minimal example to generate an image called ``bst-hello`` from an element
+called ``hello.bst`` assuming it is already built:
+
+.. code:: bash
+
+  bst-docker-import -t bst-hello hello.bst
+
+This script can also be used if you are running BuildStream inside Docker. In
+this case, you will need to supply the command that you are using to run
+BuildStream using the ``-c`` option.  If you are using the
+`bst-here wrapper script <https://gitlab.com/BuildStream/buildstream/blob/master/contrib/bst-here>`_,
+you can achieve the same results as the above example like this:
+
+.. code:: bash
+
+  bst-docker-import -c bst-here -t bst-hello hello.bst

doc/source/core_additional.rst

@@ -8,3 +8,4 @@ Additional writings
 
    additional_cachekeys
    additional_sandboxing
+   additional_docker