Move the Docker documentation out of the README and add more detail

Change-Id: I40fdbc15a8e90817de0721efc161c0c3ecf72cf7
Reviewed-by: Kai Koehne <kai.koehne@qt.io>

2 files changed, 82 insertions, 18 deletions

diff --git a/README b/README
index 9b6c5bf9c..54352a956 100644
--- a/README
+++ b/README
@@ -32,21 +32,5 @@ Installation ("make install") is not needed. It is however possible, using
 
     make install INSTALL_ROOT=$INSTALL_DIRECTORY
 
-You can also build Qbs for Windows using Docker on Windows 10 systems.
-Switch your Docker environment to use Windows containers, then run the
-following to download the Windows 10 Qbs development image:
-
-    docker pull qtproject/qbswindowsservercore
-
-The Dockerfile from which this image is built is located in the docker
-directory of the qbs source tree, should you wish to build it yourself.
-
-You can then use the image to perform builds and develop Qbs. For example:
-
-    # Run a container interactively with cmd shell access,
-    # mounting the current directory inside at C:\qbs
-    docker run -i -v %CD%:C:\qbs -w C:\qbs qtproject/qbswindowsservercore
-
-    # Perform a release build with a temporary container instance,
-    # and copy the output artifacts to the working directory
-    docker run --rm -v %CD%:C:\qbs -w C:\qbs qtproject/qbswindowsservercore cmd /c scripts\make-release-archives
+You can also build and develop Qbs using Docker. For more information,
+see "Appendix A: Building Qbs" in the Qbs Manual.
diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index 733eca941..568e09317 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -142,6 +142,86 @@
                                         implies a dependency to the Qt GUI module.
     \endtable
 
+    \section1 Docker
+
+    A set of Docker images for developing \QBS (which are maintained by the \QBS team) is available
+    \l{https://hub.docker.com/u/qbsbuild/}{on Docker Hub}.
+    Both Windows Server Core and Debian Linux container types are available.
+
+    \note The source code for the \QBS development Docker images is located in the \c{docker/}
+    directory of the \QBS source tree, if you wish to build them yourself.
+
+    \section2 Linux Containers
+
+    The easiest way to get started is to build \QBS using a Linux container. These types of
+    containers are supported out of the box on all the supported host platforms: Windows, macOS,
+    and Linux. Run the following to download the \QBS development image based on Debian 9
+    \e Stretch:
+
+    \code
+        docker pull qbsbuild/qbsdev:stretch
+    \endcode
+
+    You can then create a new container with the \QBS source directory mounted from your host
+    machine's file system, by running:
+
+    \code
+        docker run -it -v $PWD:/qbs -w /qbs qbsbuild/qbsdev:stretch
+    \endcode
+
+    Or with a slightly different syntax for Windows:
+
+    \code
+        docker run -it -v %CD%:/qbs -w /qbs qbsbuild/qbsdev:stretch
+    \endcode
+
+    You will now be in an interactive Linux shell where you can develop and build \QBS.
+
+    \section2 Windows Containers
+
+    To build \QBS for Windows using Windows containers, your host OS must be running Windows 10 Pro
+    and have Hyper-V enabled. \l{https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers}{Switch your Docker environment to use Windows containers}, then run the
+    following command to download the Windows 10 \QBS development image:
+
+    \code
+        docker pull qbsbuild/qbsdev:windowsservercore
+    \endcode
+
+    You can then create a new container with the \QBS source directory mounted from your host
+    machine's file system, by running:
+
+    \code
+        docker run -it -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore
+    \endcode
+
+    If you want to use Windows containers on a macOS or Linux host, you will have to create a
+    virtual machine running Windows 10 and register it with \c{docker-machine}. There is at least
+    \l{https://github.com/StefanScherer/windows-docker-machine}{one Open Source project}
+    that helps to facilitate this by using using Packer, Vagrant, and VirtualBox.
+
+    The \c{docker run} command to spawn a Windows container on a Unix host will look slightly
+    different (assuming \c windows is the name of the Docker machine associated with the Windows
+    container hosting VM):
+
+    \code
+        eval $(docker-machine env windows)
+        docker run -it -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore
+    \endcode
+
+    \section2 Building Release Packages
+
+    Release packages for \QBS for Windows can be built using the following command on Windows:
+
+    \code
+        docker run --rm -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\make-release-archives
+    \endcode
+
+    For building release packages for Windows on macOS or Linux:
+
+    \code
+        eval $(docker-machine env windows)
+        docker run --rm -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\\make-release-archives
+    \endcode
 */