Doc improvements

doc/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build2
+SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
 

doc/source/apis.rst

@@ -3,42 +3,36 @@ Accessing Android APIs
 ======================
 
 When writing an Android application you may want to access the normal
-Android APIs, which are available in Java. It is by calling these that
-you would normally accomplish everything from vibration, to opening
-other applications, to accessing sensor data, to controlling settings
-like screen orientation and wakelocks.
-
-These APIs can be accessed from Python to perform all of these tasks
-and many more. This is made possible by the `Pyjnius
-<http://pyjnius.readthedocs.org/en/latest/>`_ module, a Python
-library for automatically wrapping Java and making it callable from
-Python code. This is fairly simple to use, though not very Pythonic
-and inherits Java's verbosity. For this reason the Kivy organisation
-also created `Plyer <https://plyer.readthedocs.org/en/latest/>`_,
-which further wraps specific APIs in a Pythonic and cross-platform
-way - so in fact you can call the same code in Python but have it do
-the right thing also on platforms other than Android.
-
-These are both independent projects whose documentation is linked
-above, and you can check this to learn about all the things they can
-do. The following sections give some simple introductory examples,
-along with explanation of how to include these modules in your APKs.
+Android Java APIs, in order to control your application's appearance
+(fullscreen, orientation etc.), interact with other apps or use
+hardware like vibration and sensors.
+
+You can access these with `Pyjnius
+<http://pyjnius.readthedocs.org/en/latest/>`_, a Python library for
+automatically wrapping Java and making it callable from Python
+code. Pyjnius is fairly simple to use, but not very Pythonic and it
+inherits Java's verbosity. For this reason the Kivy organisation also
+created `Plyer <https://plyer.readthedocs.org/en/latest/>`_, which
+further wraps specific APIs in a Pythonic and cross-platform way; you
+can call the same code in Python but have it do the right thing also
+on platforms other than Android.
+
+Pyjnius and Plyer are independent projects whose documentation is
+linked above.  See below for some simple introductory examples, and
+explanation of how to include these modules in your APKs.
 
 
 Using Pyjnius
 -------------
 
-Pyjnius lets you call the Android API directly from Python; this let's
-you do almost everything you can (and probably would) do in a Java
-app. Pyjnius is works by dynamically wrapping Java classes, so you
-don't have to wait for any particular feature to be pre-supported.
+Pyjnius lets you call the Android API directly from Python Pyjnius is
+works by dynamically wrapping Java classes, so you don't have to wait
+for any particular feature to be pre-supported.
 
-You can include Pyjnius in your APKs by adding the `pyjnius` or
-`pyjniussdl2` recipes to your build requirements (the former works
-with Pygame/SDL1, the latter with SDL2, the need to make this choice
-will be removed later when pyjnius internally supports multiple
-Android backends). It is automatically included in any APK containing
-Kivy, in which case you don't need to specify it manually.
+You can include Pyjnius in your APKs by adding `pyjnius` to your build
+requirements, e.g. :code:`--requirements=flask,pyjnius`. It is
+automatically included in any APK containing Kivy, in which case you
+don't need to specify it manually.
 
 The basic mechanism of Pyjnius is the `autoclass` command, which wraps
 a Java class. For instance, here is the code to vibrate your device::
@@ -87,17 +81,16 @@ You can check the `Pyjnius documentation <Pyjnius_>`_ for further details.
 Using Plyer
 -----------
 
-Plyer aims to provide a much less verbose, Pythonic wrapper to
-platform-specific APIs. Android is a supported platform, but it also
-supports iOS and desktop operating systems, with the idea that the
-same Plyer code would do the right thing on any of them, though Plyer
-is a work in progress and not all platforms support all Plyer calls
-yet. This is the disadvantage of Plyer, it does not support all APIs
-yet, but you can always Pyjnius to call anything that is currently
-missing.
+Plyer provides a much less verbose, Pythonic wrapper to
+platform-specific APIs. It supports Android as well as iOS and desktop
+operating systems, though plyer is a work in progress and not all
+platforms support all Plyer calls yet. 
+
+Plyer does not support all APIs yet, but you can always Pyjnius to
+call anything that is currently missing.
 
 You can include Plyer in your APKs by adding the `Plyer` recipe to
-your build requirements. It is not included automatically.
+your build requirements, e.g. :code:`--requirements=plyer`. 
 
 You should check the `Plyer documentation <Plyer_>`_ for details of all supported
 facades (platform APIs), but as an example the following is how you
@@ -106,8 +99,4 @@ would achieve vibration as described in the Pyjnius section above::
     from plyer.vibrator import vibrate
     vibrate(10)  # in Plyer, the argument is in seconds
 
-This is obviously *much* less verbose!
-
-.. warning:: At the time of writing, the Plyer recipe is not yet
-             ported, and Plyer doesn't support SDL2. These issues will
-             be fixed soon.
+This is obviously *much* less verbose than with Pyjnius!

doc/source/bootstraps.rst

@@ -2,18 +2,16 @@
 Bootstraps
 ==========
 
+This page is about creating new bootstrap backends. For build options
+of existing bootstraps (i.e. with SDL2, Pygame, Webview etc.), see
+:ref:`build options <bootstrap_build_options>`.
+
 python-for-android (p4a) supports multiple *bootstraps*. These fulfill a
 similar role to recipes, but instead of describing how to compile a
 specific module they describe how a full Android project may be put
 together from a combination of individual recipes and other
 components such as Android source code and various build files.
 
-If you do not want to modify p4a, you don't need to worry about
-bootstraps, just make sure you specify what modules you want to use
-(or specify an existing bootstrap manually), and p4a will
-automatically build everything appropriately. The existing choices are
-explained on the :ref:`build options <bootstrap_build_options>` page.
-
 This page describes the basics of how bootstraps work so that you can
 create and use your own if you like, making it easy to build new kinds
 of Python project for Android.

doc/source/index.rst

@@ -28,7 +28,6 @@ Contents
 
    quickstart
    buildoptions
-   installation
    commands
    recipes
    bootstraps
@@ -44,4 +43,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-