update installation and packaging docs, fix some typos and improve grammar

Author: dessant

doc/sources/guide/packaging-osx.rst

@@ -24,32 +24,30 @@ for packaging. Otherwise the latest build from kivy.org using Kivy
 master will be downloaded and used.
 
 If you want to package for python 3.x.x simply download the package
-named Kivy3.7z from the download sectoin of Kivy.org and extract it
-to Kivy.app in /Applications.
-
-Then run.
+named Kivy3.7z from the download section of kivy.org and extract it
+to Kivy.app in /Applications, then run::
 
     buildozer osx debug
 
-Once the app is packaged, you might want to remove extra un needed
-packages like gstreamer framework etc from it if you don't use video.
-Same logic implies for other things you do not use, just reduce
-the package to it's minimal state that is needed for the app to run.
+Once the app is packaged, you might want to remove unneeded
+packages like gstreamer, if you don't need video support.
+Same logic applies for other things you do not use, just reduce
+the package to its minimal state that is needed for the app to run.
 
-As a example we are including the showcase example packaged using
-this method for both python 2(9.xMB) and 3(15.xMB), you can find the
-packages here 
+As an example we are including the showcase example packaged using
+this method for both Python 2 (9.xMB) and 3 (15.xMB), you can find the
+packages here:
 https://drive.google.com/drive/folders/0B1WO07-OL50_alFzSXJUajBFdnc .
 
 That's it. Enjoy!
 
-buildozer right now uses the Kivy sdk method to package your app.
+Buildozer right now uses the Kivy SDK to package your app.
 If you want to control more details about your app than buildozer
-currently offers then you can use the following method `using Kivy SDK`
-mentioned below.
+currently offers then you can use the SDK directly, as detailed in the
+section below.
 
-Using Kivy SDK
---------------
+Using the Kivy SDK
+------------------
 
 Since version 1.9.0, Kivy is released for the OS X platform in a
 self-contained, portable distribution.
@@ -96,11 +94,11 @@ To install any module you need to install the module like so::
 
 Where are the modules/files installed?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Inside the relocatable venv within the app at::
+Inside the portable venv within the app at::
 
     Kivy.app/Contents/Resources/venv/
 
-If you install a module that install's a binary for example like kivy-garden
+If you install a module that installs a binary for example like kivy-garden
 That binary will be only available from the venv above, as in after you do::
 
     kivy -m pip install kivy-garden
@@ -112,14 +110,14 @@ The garden lib will be only available when you activate this env.
     deactivate
 
 To install binary files
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Just copy the binary to the Kivy.app/Contents/Resources/venv/bin/ directory.
 
-To Include other frameworks
+To include other frameworks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Kivy.app comes with SDL2 and Gstreamer frameworks provided.
-To Include frameworks other than the ones provided do the following::
+To include frameworks other than the ones provided do the following::
 
     git clone http://github.com/tito/osxrelocator
     export PYTHONPATH=~/path/to/osxrelocator
@@ -130,12 +128,12 @@ To Include frameworks other than the ones provided do the following::
 Do not forget to replace <Framework_name> with your framework.
 This tool `osxrelocator` essentially changes the path for the
 libs in the framework such that they are relative to the executable
-within the .app. Making the Framework relocatable with the .app.
+within the .app, making the Framework portable with the .app.
 
 
 Shrinking the app size
 ^^^^^^^^^^^^^^^^^^^^^^
-The app has of considerable size right now, however the unneeded parts can be
+The app has a considerable size right now, however the unneeded parts can be
 removed from the package.
 
 For example if you don't use GStreamer, simply remove it from
@@ -165,26 +163,26 @@ This should give you a compressed dmg that will further shrink the size of your
 .. _osx_pyinstaller:
 
 
-Using Pyinstaller without brew
-------------------------------
-First install Kivy and it's dependencies without using homebrew as mentioned here
-http://kivy.org/docs/installation/installation.html#development-version
+Using PyInstaller without Homebrew
+----------------------------------
+First install Kivy and its dependencies without using Homebrew as mentioned here
+http://kivy.org/docs/installation/installation.html#development-version.
 
-Once you have kivy and it's deps installed then you need to install pyinstaller
+Once you have kivy and its deps installed, you need to install PyInstaller.
 
-let's assume we use a folder like `testpackaging`::
+Let's assume we use a folder like `testpackaging`::
 
     cd testpackaging
     git clone http://github.com/pyinstaller/pyinstaller
-    
-create a file named as touchtracer.spec in this directory and paste the following
-into it editing ::
+
+Create a file named touchtracer.spec in this directory and add the following
+code to it::
 
     # -*- mode: python -*-
-    
+
     block_cipher = None
     from kivy.tools.packaging.pyinstaller_hooks import get_deps_all, hookspath, runtime_hooks
-    
+
     a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'],
                  pathex=['/path/to/yout/folder/containing/testpackaging'],
                  binaries=None,
@@ -217,22 +215,22 @@ into it editing ::
                  icon=None,
              bundle_identifier=None)
 
-Change the paths ::
+Change the paths with your relevant paths::
 
     a = Analysis(['/path/to/yout/folder/containing/examples/demo/touchtracer/main.py'],
                 pathex=['/path/to/yout/folder/containing/testpackaging'],
     ...
     ...
     coll = COLLECT(exe, Tree('../kivy/examples/demo/touchtracer/'),
 
-By your relevant paths, then run the following command::
+Then run the following command::
 
     pyinstaller/pyinstaller.py touchtracer.spec
 
 Replace `touchtracer` with your app where appropriate.
-This will give you a <yourapp>.app in dist/ folder.
-    
-    
+This will give you a <yourapp>.app in the dist/ folder.
+
+
 Using PyInstaller and Homebrew
 ------------------------------
 .. note::
@@ -344,16 +342,3 @@ If your project depends on GStreamer::
 If you are using Python from Homebrew you currently also need the following step until `this pull request <https://github.com/Homebrew/homebrew/pull/46097>`_ gets merged::
 
     $ brew reinstall --with-python --build-bottle https://github.com/cbenhagen/homebrew/raw/patch-3/Library/Formula/gst-python.rb
-
-
-SDL 2 HEAD for ``Window.on_dropfile`` support
-"""""""""""""""""""""""""""""""""""""""""""""
-
-You can install the newest SDL 2 library which supports ``on_dropfile`` with::
-
-    $ brew reinstall --build-bottle --HEAD sdl2
-
-Or you build 2.0.3 with the following patches (untested):
-
-- https://hg.libsdl.org/SDL/rev/2cc90bb31777
-- https://hg.libsdl.org/SDL/rev/63c4d6f1f85f

doc/sources/installation/installation-osx.rst

@@ -22,39 +22,39 @@ It comes as a .7z file that contains:
 To install Kivy, you must:
 
     1. Download the latest version from http://kivy.org/#download
-       Kivy2.7z is using using python2(System Python), Kivy3.7z(Python3)
-    2. Extract it using a Unarchiver programme like http://www.kekaosx.com/en/.
+       Kivy2.7z is using using Python 2 (System Python), Kivy3.7z (Python 3)
+    2. Extract it using an archive program like http://www.kekaosx.com/en/.
     3. Copy the Kivy2.app or Kivy3.app as Kivy.app to /Applications.
-       Paste the following line onto the terminal::
-       
+       Paste the following line in the terminal::
+
         $ sudo mv Kivy2.app /Applications/Kivy.app
-           
+
     4. Create a symlink named `kivy` to easily launch apps with kivy venv::
-    
+
         $ ln -s /Applications/Kivy.app/Contents/Resources/script /usr/local/bin/kivy
-    
-    5. Examples and all the normal kivy tools are present in the Kivy.app/Contents/Resources/kivy dir                   
 
-You should now have a `kivy` script that you can use to launch your kivy app from terminal.
+    5. Examples and all the normal kivy tools are present in the Kivy.app/Contents/Resources/kivy directory.
+
+You should now have a `kivy` script that you can use to launch your kivy app from the terminal.
 
 You can just drag and drop your main.py to run your app too.
 
 
 Installing modules
 ~~~~~~~~~~~~~~~~~~
 
-Kivy package on osx uses its own virtual env that is activated when you run your app using `kivy` command.
+The Kivy SDK on OS X uses its own virtual env that is activated when you run your app using the `kivy` command.
 To install any module you need to install the module like so::
 
     $ kivy -m pip install <modulename>
 
 Where are the modules/files installed?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Inside the relocatable venv within the app at::
+Inside the portable venv within the app at::
 
     Kivy.app/Contents/Resources/venv/
 
-If you install a module that install's a binary for example like kivy-garden
+If you install a module that installs a binary for example like kivy-garden.
 That binary will be only available from the venv above, as in after you do::
 
     kivy -m pip install kivy-garden
@@ -70,10 +70,10 @@ To install binary files
 
 Just copy the binary to the /Applications/Kivy.app/Contents/Resources/venv/bin/ directory.
 
-To Include other frameworks
+To include other frameworks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Kivy.app comes with SDL2 and Gstreamer frameworks provided.
-To Include frameworks other than the ones provided do the following::
+To include frameworks other than the ones provided do the following::
 
     git clone http://github.com/tito/osxrelocator
     export PYTHONPATH=~/path/to/osxrelocator
@@ -84,7 +84,7 @@ To Include frameworks other than the ones provided do the following::
 Do not forget to replace <Framework_name> with your framework.
 This tool `osxrelocator` essentially changes the path for the
 libs in the framework such that they are relative to the executable
-within the .app. Making the Framework relocatable with the .app.
+within the .app, making the Framework portable with the .app.
 
 Start any Kivy Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/sources/installation/installation.rst

@@ -5,7 +5,7 @@ Installation
 
 We try not to reinvent the wheel, but to bring something innovative to the
 market. As a consequence, we're focused on our own code and use pre-existing,
-high-quality third-party libraries where possible.
+high quality third-party libraries where possible.
 To support the full, rich set of features that Kivy offers, several other libraries are
 required. If you do not use a specific feature (e.g. video playback), you
 don't need the corresponding dependency.
@@ -26,7 +26,7 @@ be available. For these, we recommend `SDL2 <https://www.libsdl.org/download-2.0
 Other optional libraries (mutually independent) are:
 
     * `OpenCV 2.0 <http://sourceforge.net/projects/opencvlibrary/>`_ -- Camera input.
-    * `PIL <http://www.pythonware.com/products/pil/index.htm>`_ -- Image and text display.
+    * `Pillow <https://python-pillow.github.io/>`_ -- Image and text display.
     * `PyEnchant <https://pythonhosted.org/pyenchant/>`_ -- Spelling correction.
 
 
@@ -101,8 +101,8 @@ supported version from pypi:
 OS X
 ++++
 
-Without using brew you can install the dependencies for kivy
-manually copy pasting the following commands onto a terminal::
+Without using brew you can install the dependencies for kivy by
+manually pasting the following commands in a terminal::
 
     curl -O -L https://www.libsdl.org/tmp/release/SDL2-2.0.4.dmg
     curl -O -L https://www.libsdl.org/projects/SDL_image/release/SDL2_image-2.0.0.dmg
@@ -113,8 +113,8 @@ manually copy pasting the following commands onto a terminal::
     hdiutil attach SDL2-2.0.4.dmg
     sudo cp -a /Volumes/SDL2/SDL2.framework /Library/Frameworks/
 
-This should ask you for you for your root password,  provide it and then copy paste
-the following lines onto your terminal::
+This should ask you for your root password, provide it and then paste
+the following lines in your terminal::
 
     hdiutil attach SDL2_image-2.0.0.dmg
     sudo cp -a /Volumes/SDL2_image/SDL2_image.framework /Library/Frameworks/
@@ -127,15 +127,15 @@ the following lines onto your terminal::
     pip install --upgrade --user cython pillow
 
 Now that you have all the dependencies for kivy, you need to make sure
-you have command line tools installed::
+you have the command line tools installed::
 
     xcode-select --install
 
-Goto a apropriate dir like::
+Go to an apropriate dir like::
 
     mkdir ~/code
     cd ~/code
-    
+
 You can now install kivy itself::
 
     git clone http://github.com/kivy/kivy
@@ -147,19 +147,19 @@ just point your PYTHONPATH to this dir.
 
     export PYTHONPATH=~/code/kivy:$PYTHONPATH
 
-To check if kivy is installed type the following command in your 
+To check if kivy is installed, type the following command in your
 terminal::
 
     python -c "import kivy"
 
-It should give you the a output something like the following::
+It should give you an output similar to the following::
 
     $ python -c "import kivy"
     [INFO   ] [Logger      ] Record log in /Users/quanon/.kivy/logs/kivy_15-12-31_21.txt
     [INFO   ] [Screen      ] Apply screen settings for Motolora Droid 2
     [INFO   ] [Screen      ] size=480x854 dpi=240 density=1.5 orientation=portrait
     [INFO   ] [Kivy        ] v1.9.1-stable
-    [INFO   ] [Python      ] v2.7.10 (default, Oct 23 2015, 18:05:06) 
+    [INFO   ] [Python      ] v2.7.10 (default, Oct 23 2015, 18:05:06)
     [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.5)]
 
 If using brew method to install kivy then
@@ -215,16 +215,16 @@ also run (as admin, e.g. with sudo)::
     $ python setup.py install
 
 If you want to contribute code (patches, new features) to the Kivy
-code base, please read :ref:`contributing`.
+codebase, please read :ref:`contributing`.
 
 Running the test suite
 ~~~~~~~~~~~~~~~~~~~~~~
 
 To help detect issues and behaviour changes in Kivy, a set of unittests are
 provided. A good thing to do is to run them just after your Kivy installation, and
 every time you intend to push a change. If you think something was broken
-in Kivy, perhaps a test will show this? If not, it might be a good time to write
-one .)
+in Kivy, perhaps a test will show this. (If not, it might be a good time to write
+one.)
 
 Kivy tests are based on nosetest, which you can install from your package
 manager or using pip::
@@ -239,7 +239,7 @@ Uninstalling Kivy
 ~~~~~~~~~~~~~~~~~
 
 If you are mixing multiple Kivy installations, you might be confused about where each Kivy version is
-located.  Please note that you might need to follow these steps multiple times if you have multiple
+located. Please note that you might need to follow these steps multiple times if you have multiple
 Kivy versions installed in the Python library path.
 To find your current installed version, you can use the command line::