Doc fixes

doc/source/buildoptions.rst

@@ -2,9 +2,7 @@
 Build options
 =============
 
-python-for-android provides several major choices for build
-components. This page describes the advantages and drawbacks, and
-extra technical details or requirements, in each case.
+This page contains instructions for using some of the specific python-for-android build options.
 
 
 Python version
@@ -20,9 +18,9 @@ python2
 
 Select this by adding it in your requirements, e.g. ``--requirements=python2``.
 
-This option builds Python 2.7.2 for your selected Android architecture, and
-includes it in the APK. There are no special requirements, all the
-building is done locally.
+This option builds Python 2.7.2 for your selected Android
+architecture. There are no special requirements, all the building is
+done locally.
 
 The python2 build is also the way python-for-android originally
 worked, even in the old toolchain.
@@ -35,23 +33,26 @@ python3
    Python3 support is experimental, and some of these details
    may change as it is improved and fully stabilised.
 
+.. note:: You must manually download the `CrystaX NDK
+   <https://www.crystax.net/android/ndk>`__ and tell
+   python-for-android to use it with ``--ndk-dir /path/to/NDK``.
+
 Select this by adding the ``python3crystax`` recipe to your
 requirements, e.g. ``--requirements=python3crystax``.
 
 This uses the prebuilt Python from the `CrystaX NDK
 <https://www.crystax.net/android/ndk>`__, a drop-in replacement for
-Google's official NDK which includes many improvements. As such, you
+Google's official NDK which includes many improvements. You
 *must* use the CrystaX NDK 10.3.0 or higher when building with
 python3. You can get it `here
 <https://www.crystax.net/en/download>`__.
 
-python3 inclusion should work fine, including all existing
-recipes, but internally this is handled quite differently to the
-locally built python2 so there may be bugs or surprising
-behaviours. If you come across any, feel free to `open an issue
+The python3crystax build is is handled quite differently to python2 so
+there may be bugs or surprising behaviours. If you come across any,
+feel free to `open an issue
 <https://github.com/kivy/python-for-android>`__.
 
-The experimental status also means that some features are missing and
+As this build is experimental, some features are missing and
 the build is not fully optimised so APKs are probably a little larger
 and slower than they need to be. This is currently being addressed,
 though it's not clear how the final result will compare to python2.
@@ -61,9 +62,9 @@ though it's not clear how the final result will compare to python2.
 Bootstrap
 ---------
 
-python-for-android supports multiple bootstraps, the Java and JNI code
-that starts the app and the python interpreter, then handles
-interactions with the Android OS.
+python-for-android supports multiple bootstraps, which contain the app
+backend that starts the app and the python interpreter, then
+handles interactions with the Android OS.
 
 Currently the following bootstraps are supported, but we hope that it
 it should be easy to add others if your project has different
@@ -74,30 +75,25 @@ are any improvements that would help here.
 sdl2
 ~~~~
 
-You can use this with ``--bootstrap=sdl2``, or simply include the
-``sdl2`` recipe in your ``--requirements``.
+Use this with ``--bootstrap=sdl2``, or just include the
+``sdl2`` recipe, e.g. ``--requirements=sdl2,python2``.
 
 SDL2 is a popular cross-platform depelopment library, particularly for
 games. It has its own Android project support, which
 python-for-android uses as a bootstrap, and to which it adds the
 Python build and JNI code to start it.
 
 From the point of view of a Python program, SDL2 should behave as
-normal. For instance, you can build apps with Kivy, Vispy, or PySDL2
+normal. For instance, you can build apps with Kivy or PySDL2
 and have them work with this bootstrap. It should also be possible to
 use e.g. pygame_sdl2, but this would need a build recipe and doesn't
 yet have one.
 
-.. note::
-   The SDL2 bootstrap is newer, and does not support all the old
-   features of the Pygame one. It is under active development to fix
-   these omissions.
-
 webview
 ~~~~~~~
 
-You can use this with ``--bootstrap=webview``, or simply include the
-``webviewjni`` recipe in your ``--requirements``.
+You can use this with ``--bootstrap=webview``, or include the
+``webviewjni`` recipe, e.g. ``--requirements=webviewjni,python2``.
 
 The webview bootstrap gui is, per the name, a WebView displaying a
 webpage, but this page is hosted on the device via a Python

doc/source/troubleshooting.rst

@@ -69,6 +69,51 @@ on `logcat
 <http://developer.android.com/intl/zh-cn/tools/help/logcat.html>`_ in
 particular.
 
+Unpacking an APK
+----------------
+
+It is sometimes useful to unpack a pacakged APK to see what is inside,
+especially when debugging python-for-android itself.
+
+APKs are just zip files, so you can extract the contents easily::
+
+  unzip YourApk.apk
+
+At the top level, this will always contain the same set of files::
+
+  $ ls
+  AndroidManifest.xml  classes.dex  META-INF                                res
+assets               lib          PyonicPython2interpreter-0.9-debug.apk  resources.arsc
+
+The Python distribution is in the assets folder::
+
+  $ cd assets
+  $ ls 
+  private.mp3
+
+``private.mp3`` is actually a tarball containing all your packaged
+data, and the Python distribution. Extract it::
+
+  $ tar xf private.mp3
+
+This will reveal all the Python-related files::
+
+  $ ls
+  android_runnable.pyo  include          interpreter_subprocess  main.kv   pipinterface.kv   settings.pyo
+  assets                __init__.pyo     interpreterwrapper.pyo  main.pyo  pipinterface.pyo  utils.pyo
+  editor.kv             interpreter.kv   lib                     menu.kv   private.mp3       widgets.pyo
+  editor.pyo            interpreter.pyo  libpymodules.so         menu.pyo  settings.kv
+
+Most of these files have been included by the user (in this case, they
+come from one of my own apps), the rest relate to the python
+distribution.
+
+With Python 2, the Python installation can mostly be found in the
+``lib`` folder. With Python 3 (using the ``python3crystax`` recipe),
+the Python installation can be found in a folder named
+``crystax_python``.
+
+
 Common errors
 -------------