From 15eb4fa06957df30a8b6442b508751b05d9171c2 Mon Sep 17 00:00:00 2001
From: Peter Badida <KeyWeeUsr@users.noreply.github.com>
Date: Mon, 22 Oct 2018 23:46:56 +0200
Subject: [PATCH] Update installation instructions

---
 docs/source/installation.rst | 74 ++++++++++++++++++++++++++----------
 1 file changed, 53 insertions(+), 21 deletions(-)

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index bf56f733..97bdf128 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -3,15 +3,16 @@
 Installation
 ============
 
-Pyjnius depends on `Cython <http://cython.org/>`_ and `Java
-<http://www.oracle.com/javase>`_.
+PyJNIus depends on `Cython <http://cython.org/>`_ and `Java
+<http://www.oracle.com/javase>`_ Development Kit (includes Java Runtime
+Environment).
 
 
-Installation on the Desktop
----------------------------
+Installation on GNU/Linux distributions
+---------------------------------------
 
-You need the Java JDK and JRE installed (openjdk will do), and Cython. Then,
-just type::
+You need GNU Compiler Collection (GCC), the JDK and JRE installed (openjdk will
+do), and Cython. Then, just type::
 
     sudo python setup.py install
 
@@ -49,30 +50,61 @@ pyjnius to the requirements argument when creating a dist or apk::
 Installation for Windows
 ------------------------
 
-Python and pip must be installed and present in PATH.
+Python and pip must be installed and present in ``PATH`` environment variable.
+
+
+1. Download and install JDK containing JRE:
+
+   http://www.oracle.com/technetwork/java/javase/downloads/index.html
+
+2. Edit your system and environment variables (use the appropriate Java bitness
+   and version in paths):
+
+    Add to `Environment Variables
+    <https://en.wikipedia.org/wiki/Environment_variable>`_:
+
+    * ``JAVA_HOME``: C:\\Program Files\\Java\\jdk1.7.0_79\\bin
+    * ``PATH``: C:\\Program Files\\Java\\jdk1.7.0_79\\jre\\bin\\server
+      contains ``jvm.dll`` necessary for importing and using PyJNIus.
 
+      .. note::
+         set PATH=%PATH%;C:\\Program Files\\Java\\jdk1.7.0_79\\jre\\bin\\server
 
-1. Download and install JDK and JRE:
-    http://www.oracle.com/technetwork/java/javase/downloads/index.html
+    Add to System Variables or have it present in your ``PATH``:
+        * ``PATH``: C:\\Program Files\\Java\\jdk1.7.0_79\\bin`
 
-2. Edit your system and environment variables (use the appropriate Java version):
-    Add to Environment Variables:
-        * ``JDK_HOME``: C:\\Program Files\\Java\\jdk1.7.0_79\\
-        * ``PATH``: C:\\Program Files\\Java\\jdk1.7.0_79\\jre\\bin\\server\\
-    Add to System Variables:
-        * ``PATH``: C:\\Program Files\\Java\\jdk1.7.0_79\\bin\\`
+3. Download and install C compiler:
 
-3. Download and install Microsoft Visual C++ Compiler for Python 2.7:
-    http://aka.ms/vcpython27
+   a) Microsoft Visual C++ Compiler for Python 2.7:
 
-4. Update pip and setuptools::
+      http://aka.ms/vcpython27
 
-    python -m pip install --upgrade pip setuptools
+   b) MinGWPy for Python 2.7:
+
+      https://anaconda.org/carlkl/mingwpy
+
+   c) Microsoft Visual C++ Build Tools (command-line tools subset of Visual
+      Studio) for Python 3.5 and 3.6:
+
+      https://visualstudio.microsoft.com/downloads/
+
+   For other versions see Python's `Windows Compilers wiki
+   <https://wiki.python.org/moin/WindowsCompilers>`_.
+
+4. Update `pip <https://pip.pypa.io/en/stable/installing>`_ and setuptools::
+
+      python -m pip install --upgrade pip setuptools
 
 5. Install Cython::
 
-    python -m pip install --upgrade Cython
+       python -m pip install --upgrade cython
 
 6. Install Pyjnius::
 
-    pip install pyjnius
+       pip install pyjnius
+
+   .. note::
+       In case of MinGWPy's GCC returning a ``CreateProcess failed: 5`` error
+       you need to run the command prompt with elevated permissions, so that
+       the compiler can access JDK in ``C:\Program Files\Java\jdkx.y.z_b`` or
+       ``C:\Program Files (x86)\Java\jdkx.y.z_b``.