doc: Add new document about Docker integrations

Add a new section under "Additional writings" section about how
BuildStream integrates with Docker. At present, this section includes
only two sections:

- "Run BuildStream inside Docker", that refers to existing instructions
for doing so
- "Generate Docker images", that adds instructions for using the newly
added `contrib/bst-docker-import` script

In future, this document can be extended to include the following
things:

- Importing Docker sources via `docker` source plugin - if/when the
Docker source plguin is moved from bst-external to BuildStream proper
- A Docker sandbox, if/when that is added

2 files changed, 54 insertions, 0 deletions

diff --git a/doc/source/additional_docker.rst b/doc/source/additional_docker.rst
new file mode 100644
index 000000000..ff4c35cad
--- /dev/null
+++ b/doc/source/additional_docker.rst
@@ -0,0 +1,53 @@
+
+.. _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
diff --git a/doc/source/core_additional.rst b/doc/source/core_additional.rst
index 76e523ee8..08c445630 100644
--- a/doc/source/core_additional.rst
+++ b/doc/source/core_additional.rst
@@ -8,3 +8,4 @@ Additional writings
 
    additional_cachekeys
    additional_sandboxing
+   additional_docker