Doc: Add pyside6-android-deploy

Task-number: PYSIDE-1612
Change-Id: Ib838b46e65b00884e6a11a0c5eb8902ffcaac8d4
Reviewed-by: Adrian Herrmann <adrian.herrmann@qt.io>

3 files changed, 223 insertions, 2 deletions

diff --git a/sources/pyside6/doc/deployment/deployment-pyside6-android-deploy.rst b/sources/pyside6/doc/deployment/deployment-pyside6-android-deploy.rst
new file mode 100644
index 000000000..53944f6ea
--- /dev/null
+++ b/sources/pyside6/doc/deployment/deployment-pyside6-android-deploy.rst
@@ -0,0 +1,211 @@
+.. _pyside6-android-deploy:
+
+pyside6-android-deploy: the Android deployment tool for Qt for Python
+#####################################################################
+
+``pyside6-android-deploy`` is an easy-to-use tool for deploying PySide6 applications to different
+Android architectures, namely *arm64-v8a, x86_64, x86 and armeabi-v7a*. This tool works similarly to
+the ``pyside6-deploy`` tool and uses the same configuration file ``pysidedeploy.spec`` as
+``pyside6-deploy`` to configure the deployment process. Using the deployment configuration
+options either from the command line or from ``pysidedeploy.spec``, ``pyside6-android-deploy``
+configures the deployment to be initiated and invokes `buildozer`_, a tool used for packaging Python
+applications to Android.
+
+The final output is a `.apk` or a `.aab` file created within the project's source directory. The
+`mode` option specified under the :ref:`buildozer <buildozer_key>` key in ``pysidedeploy.spec``
+determines whether a `.apk` or a `.aab` is created.
+
+.. warning:: Currently, users are required to cross-compile Qt for Python to generate the wheels
+    required for a specific Android target architecture. This requirement will disappear when
+    there are official Qt for Python Android wheels (*in progress*). Because of this
+    requirement ``pyside6-android-deploy`` will be considered in **Technical Preview**.
+    Instructions on cross-compiling Qt for Python for Android can be found
+    :ref:`here <cross_compile_android>`.
+
+.. note:: ``pyside6-android-deploy`` only works on a Linux host at the moment. This constraint
+    is also because Qt for Python cross-compilation for Android currently only works on Linux
+    systems.
+
+How to use it?
+==============
+
+Like ``pyside6-deploy``, there are :ref:`two different ways <how_pysidedeploy>` with which
+you can deploy your PySide6 application using ``pyside6-android-deploy``. The only difference is
+that for ``pyside6-android-deploy`` to work, the main Python entry point file should be named
+``main.py``.
+
+.. _pysideandroiddeploy:
+
+pysidedeploy.spec
+=================
+
+Like ``pyside6-deploy``, you can use the ``pysidedeploy.spec`` file to control the various
+parameters of the deployment process. The file has multiple sections, with each section containing
+multiple keys (parameters being controlled) assigned to a value. The advantages of such a file are
+mentioned :ref:`here <pysidedeployspec_advantages>`. The benefit of using the same
+``pysidedeploy.spec`` for both ``pyside6-deploy`` and ``pyside6-android-deploy`` is that you can
+have one single file to control deployment to all platforms.
+
+The relevant parameters for ``pyside6-android-deploy`` are:
+
+**app**
+  * ``title``: The name of the application.
+  * ``project_dir``: Project directory. The general assumption made is that the project directory
+    is the parent directory of the main Python entry point file.
+  * ``input_file``: Path to the main Python entry point file. For ``pyside6-android-deploy`` this
+    file should be named `main.py`.
+  * ``project_file``: If it exists, this points to the path to the `Qt Creator Python Project File
+    .pyproject <https://doc.qt.io/qtforpython-6/faq/typesoffiles.html
+    #qt-creator-python-project-file-pyproject>`_ file. Such a file in the project directory ensures
+    that deployment does not consider unnecessary files when bundling the executable.
+  * ``exec_directory``: The directory where the final executable is generated.
+
+**python**
+  * ``python_path``: Path to the Python executable. It is recommended to run
+    ``pyside6-android-deploy`` from a virtual environment as certain Python packages will be
+    installed onto the Python environment. However, note to keep the created virtual environment
+    outside the project directory so that ``pyside6-android-deploy`` does not try to package it
+    as well.
+  * ``android_packages``: The Python packages installed into the Python environment for deployment
+    to work. By default, the Python packages `buildozer`_ and `cpython`_ are installed.
+
+.. _qt_key:
+
+**qt**
+  * ``modules``: Comma-separated list of all the Qt modules used by the application. Just like the
+    other configuration options in ``pysidedeploy.spec``, this option is also computed automatically
+    by ``pyside6-android-deploy``. However, if you want to explicitly include certain Qt modules,
+    the module names can be appended to this list without the `Qt` prefix.
+    e.g. Network instead of QtNetwork
+  * ``plugins``: This field is *not relevant* for ``pyside6-android-deploy`` and is only specific to
+    ``pyside6-deploy``. The plugins relevant for ``pyside6-android-deploy`` are specified through
+    the ``plugins`` option under the :ref:`android <android_key>` key.
+
+.. _android_key:
+
+**android**
+  * ``wheel_pyside``: Specifies the path to the PySide6 Android wheel for a specific target
+    architecture.
+  * ``wheel_pyside``: Specifies the path to the Shiboken6 Android wheel for a specific target
+    architecture.
+  * ``plugins``: Comma-separated list of all the Qt plugins used by the application. Just like the
+    other configuration options in ``pysidedeploy.spec``, this option is also computed automatically
+    by ``pyside6-android-deploy``. However, if you want to to explicitly include certain Qt plugins,
+    the plugin names can be appended to this list. To see all the plugins bundled with PySide6, see
+    the `plugins` folder in the ``site-packages`` on your Python where PySide6 is installed. The
+    plugin name corresponds to their folder name. This field can be confused with the ``plugins``
+    option under :ref:`qt <qt_key>` key. In the future, they will be merged into one single option.
+
+.. _buildozer_key:
+
+**buildozer**
+  * ``mode``: Specifies one of the two modes - `release` and `debug`, to run `buildozer`_. The
+    `release` mode creates an *aab* while the `debug` mode creates an apk. The default mode is
+    `debug`.
+  * ``recipe_dir``: Specifies the path to the directory containing `python-for-android`_ recipes.
+    This option is automatically computed by ``pyside6-android-deploy`` during deployment. Without
+    the :ref:`--keep-deployment-files <keep_deployment_files>` option of ``pyside6-android-deploy``,
+    the `recipe_dir` will point to a temporary directory that is deleted after the final Android
+    application package is created.
+  * ``jars_dir``: Specifies the path to the Qt Android `.jar` files that are relevant for
+    creating the Android application package. This option is automatically computed by
+    ``pyside6-android-deploy`` during deployment. Just like ``recipe_dir``, this field is also
+    *not relevant* unless used with the :ref:`--keep-deployment-files <keep_deployment_files>`
+    option of ``pyside6-android-deploy``.
+  * ``ndk_path``: Specifies the path to the Android NDK used for packaging the application.
+  * ``sdk_path``: Specifies the path to the Android SDK used for packaging the application.
+  * ``local_libs``: Specifies non-Qt plugins or other libraries compatible with the Android target
+    to be loaded by the Android runtime on startup.
+  * ``sdk_path``: Specifies the path to the Android SDK used for packaging the application.
+  * ``arch``: Specifies the target architecture's instruction set. This option take one of the four
+    values - *aarch64, armv7a, i686, x86_64*.
+
+Command Line Options
+====================
+
+Here are all the command line options of ``pyside6-android-deploy``:
+
+* **-c/--config-file**: This option is used to specify the path to ``pysidedeploy.spec`` explicitly.
+
+* **--init**: Used to only create the ``pysidedeploy.spec`` file.
+  Usage::
+
+    pyside6-android-deploy --init
+
+* **-v/--verbose**: Runs ``pyside6-android-deploy`` in verbose mode.
+
+* **--dry-run**: Displays the commands being run to produce the Android application package.
+
+.. _keep_deployment_files:
+
+* **--keep-deployment-files**: When this option is added, it retains the build folders created by
+  `buildozer`_ during the deployment process. This includes the folder storing the
+  `python-for-android`_ recipes, relevant `.jar` files and even the Android Gradle project for the
+  application.
+
+* **-f/--force**: When this option is used, it assumes ``yes`` to all prompts and runs
+  ``pyside6-android-deploy`` non-interactively. ``pyside6-android-deploy`` prompts the user to
+  create a Python virtual environment, if not already in one. With this option, the current Python
+  environment is used irrespective of whether the current Python environment is a virtual
+  environment or not.
+
+* **--name**: Application name.
+
+* **--wheel-pyside**:  Path to the PySide6 Android wheel for a specific target architecture.
+
+* **--wheel-shiboken**: Path to the Shiboken6 Android wheel for a specific target architecture.
+
+* **--ndk-path**:  Path to the Android NDK used for packaging the application.
+
+* **--sdk-path**: Path to the Android SDK used for packaging the application.
+
+* **--extra-ignore-dirs**: Comma-separated directory names inside the project directory. These
+  directories will be skipped when searching for Python files relevant to the project.
+
+* **--extra-modules**:  Comma-separated list of Qt modules to be added to the application,
+  in case they are not found automatically. The module name can either be specified
+  by omitting the prefix of Qt or including it eg: both Network and QtNetwork works.
+
+.. _cross_compile_android:
+
+Cross-compile Qt for Python wheels for Android
+==============================================
+
+The cross-compilation of Qt for Python wheel for a specific Android target architecture needs to be
+done only once per Qt version, irrespective of the number of applications you are deploying.
+Currently, cross-compiling Qt for Python wheels only works with a Linux host. Follow these steps
+to cross-compile Qt for Python Android wheels.
+
+#. `Download <qt_download>`_ and install Qt version for which you would like to create Qt for Python
+   wheels.
+
+#. Cloning the Qt for Python repository::
+
+    git clone https://code.qt.io/pyside/pyside-setup
+
+#. Check out the version that you want to build, for example 6.7. The version checked out has
+   to correspond to the Qt version downloaded in Step 1::
+
+    cd pyside-setup && git checkout 6.7
+
+#. Installing the dependencies::
+
+    pip install -r requirements.txt
+    pip install -r tools/cross_compile_android/requirements.txt
+
+#. Run the cross-compilation Python script.::
+
+    python tools/cross_compile_android/main.py --plat-name=aarch64 --qt-install-path=/opt/Qt/6.7.0
+    --auto-accept-license --skip-update
+
+   *--qt-install-path* refers to the path where Qt 6.7.0 is installed. *--auto-accept-license* and
+   *--skip-update* are required for downloading and installing Android NDK and SDK if not already
+   specified through command line options or if they don't already exist in the
+   ``pyside6-android-deploy`` cache. Use --help to see all the other available options::
+
+     python tools/cross_compile_android/main.py --help
+
+.. _`buildozer`: https://buildozer.readthedocs.io/en/latest/
+.. _`python-for-android`: https://python-for-android.readthedocs.io/en/latest/
+.. _`qt_download`: https://www.qt.io/download
+.. _`cpython`: https://pypi.org/project/Cython/
diff --git a/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst b/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst
index ff5026e65..8c5af3db4 100644
--- a/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst
+++ b/sources/pyside6/doc/deployment/deployment-pyside6-deploy.rst
@@ -10,6 +10,12 @@ compiles your Python code to C code, and links with libpython to produce the fin
 The final executable produced has a ``.exe`` suffix on Windows, ``.bin`` on Linux and ``.app`` on
 macOS.
 
+.. note:: Although using a virtual environment for Python is recommended for ``pyside6-deploy``, do
+    not add the virtual environment to the application directory you are trying to deploy.
+    ``pyside6-deploy`` will try to package this venv folder and will eventually fail.
+
+.. _how_pysidedeploy:
+
 How to use it?
 ==============
 
@@ -62,6 +68,8 @@ parameters of the deployment process. The file has multiple sections, with each
 multiple keys (parameters being controlled) assigned to a value. The advantages of such a file are
 two folds:
 
+.. _pysidedeployspec_advantages:
+
 #. Using the command line, you can control the deployment parameters without specifying them each
    time. It is saved permanently in a file, and any subsequent runs much later in time
    would enable the user to be aware of their last deployment parameters.
diff --git a/sources/pyside6/doc/deployment/index.rst b/sources/pyside6/doc/deployment/index.rst
index 6f4c2d44a..36e677566 100644
--- a/sources/pyside6/doc/deployment/index.rst
+++ b/sources/pyside6/doc/deployment/index.rst
@@ -17,8 +17,9 @@ Here are a few distribution options that you can use:
 
 If you are considering Option 3, then starting with 6.4, we ship a new tool called `pyside6-deploy`
 that deploys your PySide6 application to all desktop platforms - Windows, Linux, and macOS. To know
-more about how to use the tool see :ref:`pyside6-deploy`. Additionally, you can also use other
-popular deployment tools shown below:
+more about how to use the tool see :ref:`pyside6-deploy`. For Android deployment, see
+:ref:`pyside6-android-deploy`. Additionally, you can also use other popular deployment tools shown
+below:
 
 * `fbs`_
 * `PyInstaller`_
@@ -145,6 +146,7 @@ Here's a set of tutorials on how to use these tools:
     :maxdepth: 2
 
     deployment-pyside6-deploy.rst
+    deployment-pyside6-android-deploy.rst
     deployment-fbs.rst
     deployment-pyinstaller.rst
     deployment-cxfreeze.rst