Doc: Describe adding docker devices

For building and running apps using docker images.

Fixes: QTCREATORBUG-27561
Change-Id: Ice195e73ef8eb321cd53aee5888a9f01ddcf06f8
Reviewed-by: <github-actions-qt-creator@cristianadam.eu>
Reviewed-by: hjk <hjk@qt.io>

doc/qtcreator/src/docker/creator-docker.qdoc

@@ -0,0 +1,133 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+    /*!
+    \page creator-adding-docker-devices.html
+    \previouspage creator-developing-b2qt.html
+    \nextpage creator-developing-generic-linux.html
+
+    \title Adding Docker Devices
+
+    You can add \l{ https://docs.docker.com/get-started/overview/}
+    {Docker images} as \e devices to run, debug, and analyze applications
+    built for the Docker container from \QC. A Docker device operates like
+    a virtual machine but uses less system resources at the cost of being
+    less flexible.
+
+    Docker support is experimental. While Linux, \macos, and Windows hosts are
+    supported in principle, Linux is the recommended platform.
+
+    Currently, only CMake is supported for building applications in the Docker
+    container.
+
+    You can run applications locally or in a compatible Docker container. To be
+    able to run and debug applications on Docker devices, you must install Docker
+    as well as add Docker devices and select them in the kit. \QC automatically
+    detects kits in the shared Docker directories, but you need to check that
+    they point to the correct kit items.
+
+    Use a wizard to search for Docker images available on your local Docker
+    installation and add them as devices. To access images from Docker hub or
+    other registries, you first need to pull the images using the
+    \l{https://docs.docker.com/engine/reference/commandline/pull/}{docker pull}
+    command. You can edit the Docker device preferences later in
+    \uicontrol Edit > \uicontrol Preferences > \uicontrol Devices.
+
+    To enable the experimental Docker plugin:
+
+    \list 1
+        \li In \QC, select \uicontrol Help > \uicontrol {About Plugins} >
+            \uicontrol Utilities > \uicontrol {Docker (experimental)}.
+        \li Select \uicontrol {Restart Now} to restart \QC and load the plugin.
+    \endlist
+
+    To add a Docker image as a device:
+
+    \list 1
+        \li Select \uicontrol Edit > \uicontrol Preferences > \uicontrol Devices
+            > \uicontrol Devices > \uicontrol Add > \uicontrol {Docker Device}
+            > \uicontrol {Start Wizard} to search for images in your local Docker
+            installation.
+            \image qtcreator-docker-image-selection.png "Docker Image Selection dialog"
+        \li Select the Docker image to use, and then select \uicontrol OK.
+            \note If the Docker process is not found, make sure that Docker is
+            running and the Docker CLI executable is set in PATH.
+        \li In \uicontrol Devices, check and modify Docker device preferences.
+            \image qtcreator-docker-preferences.png "Docker Device preferences"
+        \li Select \uicontrol {Run as outside user} to use the user ID and
+            group ID of the user running \QC in the Docker container.
+        \li In \uicontrol {Paths to mount}, specify host directories to mount
+            into the container, such as the project directory.
+        \li Select \uicontrol {Auto-detect Kit Items} to generate an initial
+            \l{Adding Kits}{build and run kit} for the Docker device.
+    \endlist
+
+    \section1 Specifying Paths to Mount
+
+    You can either copy your project files into the Docker container or specify
+    paths to them in \uicontrol {Paths to mount}. Shared mounts are restricted
+    to locations in the host system that can end up in the same absolute location
+    in the Docker container. On Windows, mounted drives cannot be used as shared
+    mounts.
+
+    The paths in \uicontrol {Paths to mount} are mapped one-to-one to the Docker
+    container. Select \uicontrol Insert to browse directories to add. Select
+    \uicontrol {Delete Line} to delete the selected path or \uicontrol Clear
+    to delete all paths.
+
+    \section1 Auto-detecting Kit Items
+
+    Select \uicontrol {Auto-detect Kit Items} to generate an initial
+    \l{Adding Kits}{build and run kit} for the Docker device. You can
+    either set the kit items, such \l{Adding Debuggers}{debuggers} and
+    \l{Adding Qt Versions}{Qt version}, in PATH or install them in the
+    Docker container.
+
+    Select \uicontrol {Search in PATH} to detect kit items that are set in PATH.
+
+    Select \uicontrol {Search in Selected Directories} to detect kit items in
+    the selected directories.
+
+    To view the automatically detected kit items, select
+    \uicontrol {List Auto-Detected Kit Items}. To remove
+    them, select \uicontrol {Remove Auto-Detected Kit Items}.
+
+    \section1 Editing Docker Device Kits
+
+    Select \uicontrol Edit > \uicontrol Preferences > \uicontrol Kits to check
+    that the automatically generated kit points to the appropriate kit items.
+
+    To specify build settings:
+
+        \list 1
+            \li Open a project for an application you want to develop for the
+                device.
+            \li Select \uicontrol Projects > \uicontrol {Build & Run} to enable
+                the kit that you specified above.
+        \endlist
+
+    Select \uicontrol Run to specify run settings. Usually, you can use
+    the default settings.
+*/

doc/qtcreator/src/linux-mobile/b2qtdev.qdoc

@@ -26,7 +26,7 @@
     /*!
     \page creator-developing-b2qt.html
     \previouspage creator-developing-baremetal.html
-    \nextpage creator-developing-generic-linux.html
+    \nextpage creator-adding-docker-devices.html
 
     \title Connecting Boot2Qt Devices
 

doc/qtcreator/src/linux-mobile/linuxdev.qdoc

@@ -29,7 +29,7 @@
     \previouspage creator-developing-android.html
     \nextpage studio-advanced.html
     \else
-    \previouspage creator-developing-b2qt.html
+    \previouspage creator-adding-docker-devices.html
     \nextpage creator-developing-ios.html
     \endif
 

doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -74,6 +74,13 @@
             You can connect \l{Boot2Qt} devices to the development PC to run,
             debug, and analyze applications built for them from \QC.
 
+        \if defined(qtcreator)
+        \li \l {Adding Docker Devices}
+
+            You can add Docker images as \e devices to run, debug, and analyze
+            applications built for Docker containers from \QC.
+        \endif
+
         \li \l{Connecting Generic Remote Linux Devices}
 
             If you have a tool chain for building applications for embedded

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -169,6 +169,8 @@
             \list
                 \li \l{Connecting Android Devices}
                 \li \l{Connecting Bare Metal Devices}
+                \li \l{Connecting Boot2Qt Devices}
+                \li \l{Adding Docker Devices}
                 \li \l{Connecting Generic Remote Linux Devices}
                 \li \l{Connecting iOS Devices}
                 \li \l{Connecting MCUs}