Add docs for building APK via Docker image

Author: KeyWeeUsr

doc/source/docker.rst

@@ -0,0 +1,69 @@
+.. _docker:
+
+Docker
+======
+
+Currently we use a containerized build for testing Python for Android recipes.
+Docker supports three big platforms either directly with the kernel or via
+using headless VirtualBox and a small distro to run itself on.
+
+While this is not the actively supported way to build applications, if you are
+willing to play with the approach, you can use the ``Dockerfile`` to build
+the Docker image we use in ``.travis.yml`` for CI builds and create an Android
+application with that in a container. This approach allows you to build Android
+applications on all platforms Docker engine supports. These steps assume you
+already have Docker preinstalled and set up.
+
+.. warning::
+   This approach is highly space unfriendly! The more layers (``commit``) or
+   even Docker images (``build``) you create the more space it'll consume.
+   Within the Docker image there is Android + Crystax SDK and NDK + various
+   dependencies. Within the custom diff made by building the distribution
+   there is another big chunk of space eaten. The very basic stuff such as
+   a distribution with: CPython 3, setuptools, Python for Android ``android``
+   module, SDL2 (+ deps), PyJNIus and Kivy takes almost 13 GB. Check your free
+   space first!
+
+1. Clone the repository::
+
+       git clone https://github.com/kivy/python-for-android
+
+2. Build the image with name ``p4a``::
+
+       docker build --tag p4a .
+
+   .. note::
+      You need to be in the ``python-for-android`` for the Docker build context
+      and you can optionally use ``--file`` flag to specify the path to the
+      ``Dockerfile`` location.
+
+3. Create a container from ``p4a`` image with copied ``testapps`` folder
+   in the image mounted to the same one in the cloned repo on the host::
+
+       docker run \
+           --interactive \
+           --tty \
+           --volume ".../testapps":/home/user/testapps \
+           p4a sh -c
+               '. venv/bin/activate \
+               && cd testapps \
+               && python setup_testapp_python3.py apk \
+               --sdk-dir $ANDROID_SDK_HOME \
+               --ndk-dir $ANDROID_NDK_HOME'
+
+   .. note::
+      On Windows you might need to use quotes and forward-slash path for volume
+      "/c/Users/.../python-for-android/testapps":/home/user/testapps
+
+   .. warning::
+      On Windows ``gradlew`` will attempt to use 'bash\r' command which is
+      a result of Windows line endings. For that you'll need to install
+      ``dos2unix`` package into the image.
+
+4. Preserve the distribution you've already built (optional, but recommended):
+
+       docker commit $(docker ps --last=1 --quiet) my_p4a_dist
+
+5. Find the ``.APK`` file on this location::
+
+       ls -lah testapps

doc/source/index.rst

@@ -36,6 +36,7 @@ Contents
    apis
    troubleshooting
    launcher
+   docker
    contribute
    old_toolchain/index.rst