Improved build options doc

Author: inclement

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