[doc] Add some documentation for the Software Container Plugin Example

* Minor fixes to the "Write Applications" topic that I've been looking at

Change-Id: I372729f3e08340d3a78569cb15ee05f2cc4c2e6e
Fixes: AUTOSUITE-867
Reviewed-by: Robert Griebl <robert.griebl@pelagicore.com>

3 files changed, 107 insertions, 72 deletions

diff --git a/doc/apps.qdoc b/doc/write-applications.qdoc
index f73aab20..7c13c151 100644
--- a/doc/apps.qdoc
+++ b/doc/write-applications.qdoc
@@ -44,7 +44,7 @@ stand-alone QML application, except for these three additional tasks:
 
 \section2 The Root Element
 
-It is recommended to use either an ApplicationManagerWindow or a QtObject as the root of your QML
+It's recommended to use either an ApplicationManagerWindow or a QtObject as the root of your QML
 application. This is especially important if you require similar behavior in single-process and
 multi-process mode. If you use a QtObject, any visible base elements should still be
 \l{ApplicationManagerWindow}{ApplicationManagerWindows}. Nevertheless, other root elements are
diff --git a/examples/applicationmanager/softwarecontainer-plugin/README.md b/examples/applicationmanager/softwarecontainer-plugin/README.md
deleted file mode 100644
index 57d7eb3b..00000000
--- a/examples/applicationmanager/softwarecontainer-plugin/README.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# SoftwareContainer Plugin
-
-This is a very basic PoC integration of Pelagicore's Software-Containers
-
-[https://github.com/Pelagicore/softwarecontainer][]
-
-Please also read the "Containers" page in the official Qt Application Manager
-documentation:
-[https://doc-snapshots.qt.io/qtapplicationmanager/containers.html]
-
-Parts of the container configuration are hardcoded in `softwarecontainer.cpp`,
-while all of the capability definition is in the JSON manifest at
-`service-manifest.d/io.qt.ApplicationManager.Application/`.
-
-The Wayland/OpenGL pass-through is tested against Intel GPUs and VMware's
-virtual GPU.
-
-The softwarecontainer-agent needs to be started as root. By default it will
-register itself on the system D-Bus, so a policy file must be in place,
-allowing it to register itself on the system-bus. If you want to run the
-agent on the session bus instead (via the `--session-bus` parameter), you
-have to add the following to one of your config.yaml files:
-```
-containers:
-  softwarecontainer:
-    dbus: 'session'
-```
-
-Passing the service-manifest directory that comes with the plugin via
-`-m` is mandatory - otherwise the container setup will fail due to the
-missing `io.qt.ApplicationManager.Application` capability.
-
-You have to make sure that the agent has access to the same session-bus
-that the application-manager is using, if you intend on forwarding this
-bus. This is a bit tricky if the agent is run as root and the application-
-manager as non-root user, since the default session-bus policy in most
-distros disallows root to access user session-busses: the workaround is to
-add a `<allow user="root"/>` policy in `/etc/dbus-1/session.conf`.
-
-Please do also not forget to tell the agent about your environment, when
-running it via sudo:
-```
-sudo XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR
-DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS softwarecontainer-agent -m
-/path/to/application-manager/examples/softwarecontainer-plugin/service-manifest.d/
-```
-
-On the AM side, you need to activate the plugin by adding something like
-this to one of your config.yaml files:
-```
-plugins:
-   container: [ "/path/to/libsoftwarecontainer-plugin.so" ]
-```
-In order to actually run apps within softwarecontainers, you have to add a
-container selection configuration:
-[https://doc-snapshots.qt.io/qtapplicationmanager/containers.html#container-selection-configuration][]
-
-
-Please be aware that for easier development on the desktop, you normally want
-your $HOME directory mounted into the container in read-only mode, so you do
-not have to install your application-manager into /usr/ after every build
-(given that your build directory is somewhere in $HOME, the container would
-not see the appman-launcher-qml binary).
-This is *not* done by default, but you can activate this behavior by adding
-this to one of your config.yaml files:
-
-```
-containers:
-  softwarecontainer:
-    bindMountHome: yes
-```
diff --git a/examples/applicationmanager/softwarecontainer-plugin/doc/src/softwarecontainer-plugin.qdoc b/examples/applicationmanager/softwarecontainer-plugin/doc/src/softwarecontainer-plugin.qdoc
new file mode 100644
index 00000000..72fc309a
--- /dev/null
+++ b/examples/applicationmanager/softwarecontainer-plugin/doc/src/softwarecontainer-plugin.qdoc
@@ -0,0 +1,106 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Luxoft Application Manager.
+**
+** $QT_BEGIN_LICENSE:FDL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite 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.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+
+\example applicationmanager/softwarecontainer-plugin
+\brief Learn how to integrate Software Containers with the Application Manager.
+\ingroup applicationmanager-examples
+\title Software Container Plugin example
+
+\section1 Introduction
+
+This example shows how to integrate \l{https://github.com/Pelagicore/softwarecontainer
+{Pelagicore's Software Containers} with the Application Manager.
+
+\note As a prerequisite, familiarize yourself with \l{Containers} beforehand.
+
+In \c softwarecontainer.cpp, parts of the container's configuration is hardcoded; all of the
+capability definition is in the JSON manifest file located in
+\c{service-manifest.d/io.qt.AppliciationManager.Application/}.
+
+The Wayland/OpenGL passthrough is tested against Intel GPUs and VMWare's virtual GPU.
+
+\section1 Run the Software Container Agent
+
+To run the softwarecontainer-agent, you must start it as root. By default, this agent registers
+itself on the system D-Bus. So, you need to have a policy file in place, to allow the agent to
+register itself on the system-bus.
+
+If you want to run the agent on the session bus instead, via the \c{--session-bus} parameter,
+then you have to add the following lines to one of your \c config.yaml files:
+
+\code
+containers:
+  softwarecontainer:
+    dbus: 'session'
+\endcode
+
+It's mandatory to pass the service manifest directory that comes with the plugin via \c{-m}.
+Otherwise, the container setup fails due to the missing \c{io.qt.ApplicationManager.Application}
+capability.
+
+Make sure that the agent has access to the same session bus that the application manager uses,
+if you intend on forwarding this bus. If the agent is run as root, but the application manager is
+a non-root user, this can be tricky -- since the default session bus policy in most Linux distros
+disallows root to access user session busses. However, you can workaround this issue by adding
+an \c{<allow user="root"/>} policy within the \c{<policy context="default">} element in
+\c{/etc/dbus-1/session.conf}.
+
+Additionally, make sure to tell the agent about your environment, when running it via sudo:
+
+\code
+sudo XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR
+DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS softwarecontainer-agent -m
+/path/to/application-manager/examples/softwarecontainer-plugin/service-manifest.d/
+\endcode
+
+On the Application Manager side, you need to activate the plugin by adding a line similar to the
+one shown below, to one of your \c config.yaml files:
+
+\code
+plugins:
+   container: [ "/path/to/libsoftwarecontainer-plugin.so" ]
+\endcode
+
+To actually run applications within software containers, you have to add a container selection
+configuration. For more information, see \l{Container Selection Configuration}.
+
+To simplify developing on the desktop, normally, you want your \c $HOME directory mounted into
+the container in \c read-only mode. This way, you don't have to install your application manager
+into \c{/usr/} after every build. This behavior only works, given that your build direcctory is
+located somewhere in \c{$HOME}, otherwise the container won't see the appman-launcher-qml binary.
+This behavior is \b not enabled by default; but you can activate it with the following lines in
+one of your \c config.yaml files:
+
+\code
+containers:
+  softwarecontainer:
+    bindMountHome: yes
+\endcode
+
+*/