From 0d23ba91be083f64b4fb999b551f2a6bf4067c46 Mon Sep 17 00:00:00 2001 From: Richard Larkin Date: Sun, 21 Oct 2018 22:57:44 +0200 Subject: [PATCH] doc tweaks, grammar fixes and discord contact channel --- doc/source/apis.rst | 18 +++++++++--------- doc/source/bootstraps.rst | 5 +++-- doc/source/buildoptions.rst | 6 +++--- doc/source/distutils.rst | 2 +- doc/source/index.rst | 6 +++--- doc/source/launcher.rst | 10 +++++----- doc/source/quickstart.rst | 6 +++--- doc/source/recipes.rst | 16 ++++++++-------- doc/source/services.rst | 2 +- doc/source/troubleshooting.rst | 2 +- 10 files changed, 37 insertions(+), 36 deletions(-) diff --git a/doc/source/apis.rst b/doc/source/apis.rst index 4d564ceda2..bb46f2e339 100644 --- a/doc/source/apis.rst +++ b/doc/source/apis.rst @@ -97,7 +97,7 @@ 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 +Plyer does not support all APIs yet, but you can always use Pyjnius to call anything that is currently missing. You can include Plyer in your APKs by adding the `Plyer` recipe to @@ -136,13 +136,13 @@ code:: from jnius import autoclass def open_url(url): - Intent = autoclass('android.content.Intent') - Uri = autoclass('android.net.Uri') - browserIntent = Intent() - browserIntent.setAction(Intent.ACTION_VIEW) - browserIntent.setData(Uri.parse(url)) - currentActivity = cast('android.app.Activity', mActivity) - currentActivity.startActivity(browserIntent) + Intent = autoclass('android.content.Intent') + Uri = autoclass('android.net.Uri') + browserIntent = Intent() + browserIntent.setAction(Intent.ACTION_VIEW) + browserIntent.setData(Uri.parse(url)) + currentActivity = cast('android.app.Activity', mActivity) + currentActivity.startActivity(browserIntent) class AndroidBrowser(object): def open(self, url, new=0, autoraise=True): @@ -167,7 +167,7 @@ immediately when your app has finished loading, due to a limitation with the way we check if the app has properly started. In this case, the splash screen overlaps the app gui for a short time. -You can dismiss the splash screen as follows. Run this code from your +You can dismiss the splash screen by running this code from your app build method (or use ``kivy.clock.Clock.schedule_once`` to run it in the following frame):: diff --git a/doc/source/bootstraps.rst b/doc/source/bootstraps.rst index c522933316..ef59293221 100644 --- a/doc/source/bootstraps.rst +++ b/doc/source/bootstraps.rst @@ -14,13 +14,14 @@ components such as Android source code and various build files. 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. +of Python projects for Android. Creating a new bootstrap ------------------------ -A bootstrap class consists of just a few basic components, though one of them must do a lot of work. +A bootstrap class consists of just a few basic components, though one of them +must do a lot of work. For instance, the SDL2 bootstrap looks like the following:: diff --git a/doc/source/buildoptions.rst b/doc/source/buildoptions.rst index bb95d3969c..5b962b84ec 100644 --- a/doc/source/buildoptions.rst +++ b/doc/source/buildoptions.rst @@ -85,7 +85,7 @@ The sdl2 bootstrap supports the following additional command line options (this list may not be exhaustive): - ``--private``: The directory containing your project files. -- ``--package``: The Java package name for your project. Choose e.g. ``org.example.yourapp``. +- ``--package``: The Java package name for your project. e.g. ``org.example.yourapp``. - ``--name``: The app name. - ``--version``: The version number. - ``--orientation``: Usually one of ``portait``, ``landscape``, @@ -145,7 +145,7 @@ started), it will instead display a loading screen until the server is ready. - ``--private``: The directory containing your project files. -- ``--package``: The Java package name for your project. Choose e.g. ``org.example.yourapp``. +- ``--package``: The Java package name for your project. e.g. ``org.example.yourapp``. - ``--name``: The app name. - ``--version``: The version number. - ``--orientation``: Usually one of ``portait``, ``landscape``, @@ -206,7 +206,7 @@ options (this list may not be exhaustive): - ``--dir``: The directory containing your project files if you want them to be unpacked to the external storage directory rather than the app private directory. -- ``--package``: The Java package name for your project. Choose e.g. ``org.example.yourapp``. +- ``--package``: The Java package name for your project. e.g. ``org.example.yourapp``. - ``--name``: The app name. - ``--version``: The version number. - ``--orientation``: One of ``portait``, ``landscape`` or ``sensor`` diff --git a/doc/source/distutils.rst b/doc/source/distutils.rst index aaa15f7680..17a4070071 100644 --- a/doc/source/distutils.rst +++ b/doc/source/distutils.rst @@ -35,7 +35,7 @@ The Android package name uses ``org.test.lowercaseappname`` if not set explicitly. The ``--private`` argument is set automatically using the -package_data, you should *not* set this manually. +package_data. You should *not* set this manually. The target architecture defaults to ``--armeabi``. diff --git a/doc/source/index.rst b/doc/source/index.rst index 991fc80074..31aaf82bc3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -2,16 +2,16 @@ python-for-android ================== python-for-android is an open source build tool to let you package -Python code into standalone android APKs that can be passed around, +Python code into standalone android APKs. These can be passed around, installed, or uploaded to marketplaces such as the Play Store just like any other Android app. This tool was originally developed for the `Kivy cross-platform graphical framework `_, but now supports multiple bootstraps and can be easily extended to -package other types of Python app for Android. +package other types of Python apps for Android. python-for-android supports two major operations; first, it can compile the Python interpreter, its dependencies, backend libraries -and python code for Android devices. This stage is fully customisable, +and python code for Android devices. This stage is fully customisable: you can install as many or few components as you like. The result is a standalone Android project which can be used to generate any number of different APKs, even with different names, icons, Python code etc. diff --git a/doc/source/launcher.rst b/doc/source/launcher.rst index 6d42b8c74e..b5245f406d 100644 --- a/doc/source/launcher.rst +++ b/doc/source/launcher.rst @@ -4,7 +4,7 @@ Launcher ======== The Kivy Launcher is an Android application that can run any Kivy app -stored in `kivy` folder on SD Card. You can download the latest stable +stored in the `kivy` folder on the SD Card. You can download the latest stable version for your android device from the `Play Store `_. @@ -13,7 +13,7 @@ permissions, usually listed in the description in the store. Those aren't always enough for an application to run or even launch if you work with other dependencies that are not packaged. -The Kivy Launcher is intended for quick and simple testing, for +The Kivy Launcher is intended for quick and simple testing. For anything more advanced we recommend building your own APK with python-for-android. @@ -22,7 +22,7 @@ Building The Kivy Launcher is built using python-for-android. To get the most recent versions of packages you need to clean them first, so that the packager won't -grab an old (cached) package instead of fresh one. +grab an old (cached) package instead of a fresh one. .. highlight:: none @@ -78,8 +78,8 @@ to change other settings. After you set your `android.txt` file, you can now run the launcher and start any available app from the list. -To differentiate between apps in ``/sdcard/kivy`` you can include an icon -named ``icon.png`` to the folder. The icon should be a square. +To differentiate between apps in ``/sdcard/kivy``, you can include an icon +named ``icon.png`` in the folder. The icon should be a square. Release on the market --------------------- diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index e6a75331b1..62cde5081e 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -38,7 +38,7 @@ Installation Installing p4a ~~~~~~~~~~~~~~ -p4a is now available on on Pypi, so you can install it using pip:: +p4a is now available on Pypi, so you can install it using pip:: pip install python-for-android @@ -195,8 +195,8 @@ Getting help If something goes wrong and you don't know how to fix it, add the ``--debug`` option and post the output log to the `kivy-users Google -group `__ or irc -channel #kivy at irc.freenode.net . +group `__ or the +kivy `#support Discord channel `_. See :doc:`troubleshooting` for more information. diff --git a/doc/source/recipes.rst b/doc/source/recipes.rst index 98b5813d07..329fe25e5c 100644 --- a/doc/source/recipes.rst +++ b/doc/source/recipes.rst @@ -12,7 +12,7 @@ to take care of compilation for any compiled components, as these must be compiled for Android with the correct architecture. python-for-android comes with many recipes for popular modules. No -recipe is necessary to use of Python modules with no +recipe is necessary for Python modules which have no compiled components; these are installed automaticaly via pip. If you are new to building recipes, it is recommended that you first @@ -76,7 +76,7 @@ The actual build process takes place via three core methods:: These methods are always run in the listed order; prebuild, then build, then postbuild. -If you defined an url for your recipe, you do *not* need to manually +If you defined a url for your recipe, you do *not* need to manually download it, this is handled automatically. The recipe will automatically be built in a special isolated build @@ -89,7 +89,7 @@ context manager defined in toolchain.py:: def build_arch(self, arch): super(YourRecipe, self).build_arch(arch) with current_directory(self.get_build_dir(arch.arch)): - with open('example_file.txt', 'w'): + with open('example_file.txt', 'w') as fileh: fileh.write('This is written to a file within the build dir') The argument to each method, ``arch``, is an object relating to the @@ -192,7 +192,7 @@ its current status:: shprint(sh.echo, '$PATH', _env=env) You can also override the ``get_recipe_env`` method to add new env -vars for the use of your recipe. For instance, the Kivy recipe does +vars for use in your recipe. For instance, the Kivy recipe does the following when compiling for SDL2, in order to tell Kivy what backend to use:: @@ -350,12 +350,12 @@ For reference, the code that accomplishes this is the following:: shprint(sh.find, build_lib[0], '-name', '*.o', '-exec', env['STRIP'], '{}', ';', _env=env) -The failing build and manual cythonisation is necessary, first to +The failing build and manual cythonisation is necessary, firstly to make sure that any .pyx files have been generated by setup.py, and -second because cython isn't installed in the hostpython build. +secondly because cython isn't installed in the hostpython build. This may actually fail if the setup.py tries to import cython before -making any pyx files (in which case it crashes too early), although +making any .pyx files (in which case it crashes too early), although this is probably not usually an issue. If this happens to you, try patching to remove this import or make it fail quietly. @@ -377,7 +377,7 @@ Using an NDKRecipe ------------------ If you are writing a recipe not for a Python module but for something -that would normall go in the JNI dir of an Android project (i.e. it +that would normally go in the JNI dir of an Android project (i.e. it has an ``Application.mk`` and ``Android.mk`` that the Android build system can use), you can use an NDKRecipe to automatically set it up. The NDKRecipe overrides the normal ``get_build_dir`` method to diff --git a/doc/source/services.rst b/doc/source/services.rst index b775081e86..c63b2ce1be 100644 --- a/doc/source/services.rst +++ b/doc/source/services.rst @@ -92,7 +92,7 @@ do pass it, the service can make use of this argument. The service argument is made available to your service via the 'PYTHON_SERVICE_ARGUMENT' environment variable. It is exposed as a simple string, so if you want to pass in multiple values, we would recommend using -the json module to encode and decode mode complex data. +the json module to encode and decode more complex data. :: from os import environ diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst index 2b53ba41df..3b47674d54 100644 --- a/doc/source/troubleshooting.rst +++ b/doc/source/troubleshooting.rst @@ -11,7 +11,7 @@ full debug output including the output of all the external tools used in the compilation and packaging steps. If reporting a problem by email or Discord, it is usually helpful to -include this full log, via e.g. a `pastebin +include this full log, e.g. via a `pastebin `_ or `Github gist `_.