Refresh installation and build docs

docs/source/building.rst

@@ -0,0 +1,42 @@
+.. _building:
+
+Building PyJNIus
+================
+
+Building PyJNIus is necessary for development purposes, or if there is no 
+pre-built binary for your particular platform. 
+
+Like installation of PyJNIus, building PyJNIus requires a  `Java Development Kit
+<https://www.oracle.com/java/technologies/downloads/>`_  (JDK)
+to be installed.
+
+Apart from the JDK, the build requirements for each platform are as follows:
+
+ - Linux: the `GNU Compiler Collection <https://gcc.gnu.org/>`_ (GCC), e.g. using 
+   `apt-get install build-essentials` on Debian-based distributions.
+ - Windows: `Microsoft Visual C++ Build Tools <https://visualstudio.microsoft.com/downloads/>`_ 
+   (the command-line tools subset of Visual Studio). 
+   For more information or options, see Python's `Windows Compilers wiki
+   <https://wiki.python.org/moin/WindowsCompilers>`_.
+ - macOS: `Xcode command-line tools <https://mac.install.guide/commandlinetools/index.html>`_.
+
+In all cases, after checking out PyJNIus from GitHub, it can be *built* and installed using::
+
+     pip install .
+
+This installs `Cython <https://cython.org/>`_ (as specified in the 
+`pyproject.toml <https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/>`_) 
+in a Python build environment. On all platforms, if PyJNIus cannot find your JDK, you can set 
+the `JAVA_HOME` shell environment variable (this is often needed on Windows).
+
+If you want to compile the PyJNIus extension within the directory for any development,
+just type::
+
+    make
+
+You can run the tests suite to make sure everything is running right::
+
+    make tests
+
+In these cases, you may need to have `Cython <https://pypi.org/project/Cython/>`_ 
+and `pytest <https://pypi.org/project/pytest/>`_ installed in the current Python environment.

docs/source/index.rst

@@ -18,6 +18,7 @@ documentation.
    quickstart
    android
    api
+   building
    packaging
 
 Indices and tables

docs/source/installation.rst

@@ -3,28 +3,23 @@
 Installation
 ============
 
-PyJNIus depends on `Cython <http://cython.org/>`_ and the `Java
-<http://www.oracle.com/javase>`_ Development Kit (includes the Java Runtime
-Environment).
+PyJNIus has pre-compiled binaries on PyPi for recent Python versions on Linux,
+macOS and Windows.
 
+On each platform::
 
-Installation on GNU/Linux distributions
----------------------------------------
+   pip install pyjnius
 
-You need the GNU Compiler Collection (GCC), the JDK and JRE installed (openjdk
-will do), and Cython. Then, just type::
+should successfully install the package.
 
-    sudo python setup.py install
-
-If you want to compile the extension within the directory for any development,
-just type::
-
-    make
-
-You can run the tests suite to make sure everything is running right::
-
-    make tests
+If there is no pre-compiled binary available, pip install will aim to compile
+a binary on your operating system. For more information see the :ref:`building` 
+documentation.
 
+You will need the Java JDK installed (`OpenJDK <https://openjdk.org/>`_ is fine).
+PyJNIus searches for Java in the usual places on each operating system. If PyJNIus 
+cannot find Java, set the `JAVA_HOME` environment variable (this is often needed 
+`on Windows <https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux#windows>`_).
 
 Installation for Android
 ------------------------
@@ -47,102 +42,6 @@ pyjnius to the requirements argument when creating a dist or apk::
   p4a apk --requirements=pyjnius
 
 
-Installation for Windows
-------------------------
-
-Python and pip must be installed and present in the ``PATH`` environment variable.
-
-
-1. Download and install the JDK containing the 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 the paths):
-
-    Add to your `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 the ``jvm.dll`` necessary for importing and using PyJNIus.
-
-      .. note::
-         set PATH=%PATH%;C:\\Program Files\\Java\\jdk1.7.0_79\\jre\\bin\\server
-
-    Add to System Variables or have it present in your ``PATH``:
-        * ``PATH``: C:\\Program Files\\Java\\jdk1.7.0_79\\bin`
-
-3. Download and install the C compiler:
-
-   a) Microsoft Visual C++ Compiler for Python 2.7:
-
-      http://aka.ms/vcpython27
-
-   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
-
-6. 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 the JDK in ``C:\Program Files\Java\jdkx.y.z_b``
-       or ``C:\Program Files (x86)\Java\jdkx.y.z_b``.
-
-
-Installation for macOS
-----------------------
-
-Python and pip must be installed and present in the ``PATH`` environment variable.
-
-
-1. Download and install the JDK containing the 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 the paths):
-
-    Add to your `Environment Variables
-    <https://en.wikipedia.org/wiki/Environment_variable>`_:
-
-    * ``export JAVA_HOME=/usr/libexec/java_home``
-
-3. Install Xcode command-line tools.
-
-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
-
-6. Install Pyjnius::
-
-       pip install pyjnius
-
-
 Installation for Conda
 ----------------------
 

docs/source/packaging.rst

@@ -3,8 +3,8 @@
 Packaging
 =========
 
-For Packaging we use `PyInstaller <http://www.pyinstaller.org/>`_ and with
-these simple steps we will create a simple executable containing PyJNIus
+For Packaging, we suggest use of `PyInstaller <http://www.pyinstaller.org/>`_. 
+With these simple steps we will create a simple executable containing PyJNIus
 that prints the path of currently used Java. These steps assume you have
 a supported version of Python for PyJNIus and PyInstaller available together
 with Java installed (necessary for running the application).

docs/source/quickstart.rst

@@ -4,13 +4,14 @@ Quickstart
 ==========
 
 Eager to get started? This page will give you a good introduction to Pyjnius. It assumes
-you have already Pyjnius installed. If you do not, head over the
-:ref:`installation` section.
+you have already PyJNIus installed. If you do not, ensure you have a Java JDK installed, 
+then try `pip install pyjnius` - you can head over to the :ref:`installation` section 
+for more information.
 
 A minimal example
 -----------------
 
-A minimal Pyjnius example looks something like this::
+A minimal PyJNIus example looks something like this::
 
     from jnius import autoclass
 
@@ -24,7 +25,7 @@ A minimal Pyjnius example looks something like this::
 
 Just save it as `test.py` (or something similar) and run it with your Python
 interpreter. Make sure not to call your application `jnius.py` because it would
-conflict with Pyjnius itself::
+conflict with PyJNIus itself::
 
     $ python test.py
     world
@@ -39,7 +40,7 @@ To load nested java classes, use the "$" separator as so::
 Automatic recursive inspection
 ------------------------------
 
-Pyjnius uses Java reflection to give you a new autoclass() if the return type is
+PyJNIus uses Java reflection to give you a new autoclass() if the return type is
 not a native type. Let's see this example::
 
     System = autoclass('java.lang.System')