Improve documentation.

Author: anthony-tuininga

README.md

@@ -1,31 +1,17 @@
 # Open Source Python/Oracle Utility - cx_Oracle
 
-cx_Oracle is a Python extension module that enables access to Oracle Database
-and conforms to the Python database API 2.0 specifications with a considerable
-number of additions and a couple of exclusions. The time data type is not
-supported by Oracle and is therefore not implemented. The method
-cursor.nextset() is not implemented either as the DB API specification assumes
-an implementation of cursors that does not fit well with Oracle's
-implementation of cursors and implicit results. See the method
-cursor.getimplicitresults() for more information.
-
-See [PEP 249][1] for more information on the Python database API specification.
-See the [documentation][2] for a complete description of the module's
-capabilities.
+cx_Oracle is a Python extension module that enables access to Oracle Database.
+It conforms to the [Python database API 2.0 specification][1] with a
+considerable number of additions and a couple of exclusions.
 
-cx_Oracle is licensed under a BSD license which you can find [here][3].
+cx_Oracle is licensed under a [BSD license] which you can find [here][3].
 
-cx_Oracle has been tested with Python version 2.7, and with versions 3.4 and
+cx_Oracle 6 has been tested with Python version 2.7, and with versions 3.4 and
 higher. You can use cx_Oracle with Oracle 11.2, 12.1 and 12.2 client libraries,
 allowing connection to multiple Oracle Database versions. Oracle's standard
 client-server version interoperability allows connection to both older and
-newer databases, for example Oracle 11.2 client libraries can connect to Oracle
-Database 10.2 or later.
-
-Please note that an Oracle client (or server) installation is required in order
-to use cx_Oracle. If you do not require the tools that come with a full client
-installation, it is recommended to install the [Instant Client][4].
-which is far easier to install.
+newer databases, for example Oracle 12.2 client libraries can connect to Oracle
+Database 11.2 or later.
 
 ## Help
 
@@ -38,35 +24,33 @@ See the [cx_Oracle Documentation][2] and [Release Notes][14].
 
 ## Installation
 
-The simplest way to install cx_Oracle 6 Beta is with pip:
+See [cx_Oracle Installation][15] for detailed instructions.
 
-    python -m pip install cx_Oracle --pre
+- The simplest way to install cx_Oracle 6 RC2 is with pip:
 
-If a binary wheel package is not available on [PyPI][6] for your
-platform, the source package will be used.
+  `python -m pip install cx_Oracle --pre`
 
-If you prefer, the source package can be downloaded manually from [PyPI][6] and
-extracted, after which the following commands should be run:
+  If a binary wheel package is not available on [PyPI][6] for your platform, the
+  source package will be used.
 
-    python setup.py build
-    python setup.py install
-
-Note that if you download a source zip file directly from GitHub that
-you will also need to download an [ODPI-C][10] source zip file and
-extract it inside a directory called "odpi".
+- After cx_Oracle is installed, Oracle client libraries must also be installed
+  and configured. These can be from Oracle Instant Client, from a local Oracle
+  Database, or from a full Oracle Client installation.
 
-After cx_Oracle is installed, Oracle client libraries must also be
-installed and configured.  If you need the libraries, you can download
-and unzip the [Oracle Instant Client][4] 'Basic' package for your
-platform and set PATH, LD_LIBRARY_PATH, or similar platform-specific
-library path loading environment.  See the
-[installation notes for ODPI-C][13] for help with installing and configuring an
-Oracle client.
+  If you need the libraries, download and unzip the [Oracle Instant Client][4]
+  'Basic' package for your platform and set PATH, LD_LIBRARY_PATH, or similar
+  platform-specific library path loading environment.  See
+  the [installation notes for ODPI-C][13] for help.
 
 Versions 11.2, 12.1 and 12.2 of the Oracle Client libraries on Linux,
 Windows and macOS are supported.  Users have also reported success
 with other platforms.
 
+Note that if you download a source zip file directly from GitHub that
+you will also need to download an [ODPI-C][10] source zip file and
+extract it inside the directory called "odpi".
+
+
 ## Usage Example
 
 
@@ -176,6 +160,13 @@ the modules in the [cx_PyOracleLib][8] projects.
 
 - Oracle Database High Availability Features, such as FAN notifications and Transaction Guard support.
 
+**DB API specification exclusions**: The time data type is not
+supported by Oracle and is therefore not implemented. The method
+`cursor.nextset()` is not implemented either as the DB API specification assumes
+an implementation of cursors that does not fit well with Oracle's implementation
+of cursors and implicit results. See the method `cursor.getimplicitresults()`
+for more information.
+
 [1]: https://www.python.org/dev/peps/pep-0249
 [2]: http://cx-oracle.readthedocs.io
 [3]: https://github.com/oracle/python-cx_Oracle/blob/master/LICENSE.txt
@@ -190,3 +181,4 @@ the modules in the [cx_PyOracleLib][8] projects.
 [12]: https://github.com/oracle/python-cx_Oracle/tree/master/samples
 [13]: https://oracle.github.io/odpi/doc/installation.html
 [14]: http://cx-oracle.readthedocs.io/en/latest/releasenotes.html
+[15]: http://cx-oracle.readthedocs.io/en/latest/installation.html

doc/README.md

@@ -0,0 +1,13 @@
+The generated cx_Oracle documentation is at http://cx-oracle.readthedocs.io/
+
+This directory contains the documentation source.  It is written using reST
+(re-Structured Text) format source files which are processed using Sphinx and
+turned into HTML, PDF or ePub documents. If you wish to build these yourself,
+you need to install Sphinx. Sphinx is available on many Linux distributions as a
+pre-built package. You can also install Sphinx on all platforms using the Python
+package manager "pip". For more information on Sphinx, please visit this page:
+
+http://www.sphinx-doc.org
+
+Once Sphinx is installed, the supplied Makefile can be used to build the
+different targets.

doc/src/installation.rst

@@ -19,6 +19,8 @@ After cx_Oracle has been installed, you must also `Install Oracle Client`_, if
 that has not been done already. Oracle Client versions 12.2, 12.1 and 11.2
 are supported.
 
+Note installation has changed from cx_Oracle 5.  When using Oracle
+Instant Client, you should not set ``ORACLE_HOME``.
 
 Install Using Pip
 =================
@@ -30,9 +32,13 @@ on all platforms is::
 
 This will download and install a pre-compiled binary matching your platform
 and architecture automatically, if one is available. Pre-compiled binaries are
-available for Windows and Linux. If a pre-compiled binary is not
-available, the source will be downloaded, compiled and the resulting binary
-installed.
+available for Windows and Linux.
+
+If a pre-compiled binary is not available, the source will be
+downloaded, compiled and the resulting binary installed.  On macOS,
+make you are not using the bundled Python - use `Homebrew
+<https://brew.sh>`__ or `Python.org
+<https://www.python.org/downloads>`__ instead.
 
 
 Install Using GitHub
@@ -46,6 +52,21 @@ In order to install using the source on GitHub, use the following commands::
     git submodule update
     python setup.py install
 
+Note that if you download a source zip file directly from GitHub then
+you will also need to download an `ODPI-C
+<https://github.com/oracle/odpi>`__ source zip file and extract it
+inside the directory called "odpi".
+
+Install Using Source from PyPI
+==============================
+
+The source package can be downloaded manually from
+`PyPI <https://pypi.python.org/pypi/cx_Oracle>`__ and extracted, after
+which the following commands should be run:
+
+    python setup.py build
+    python setup.py install
+
 
 Install Using RPM
 =================
@@ -79,6 +100,14 @@ index.html>`__. Only the "Basic" or "Basic Light" package is required. Oracle
 Client libraries are also available in any Oracle Database installation or
 full Oracle Client installation.
 
+On Windows, `Microsoft Windows Redistributables
+<https://oracle.github.io/odpi/doc/installation.html#windows>`__
+matching the version of the Oracle client libraries need to be
+installed.
+
+Oracle Database
+===============
+
 Oracle Client libraries allow connection to older and newer databases.
 In summary, Oracle Client 12.2 can connect to Oracle Database 11.2 or
 greater. Oracle Client 12.1 can connect to Oracle Database 10.2 or
@@ -146,7 +175,6 @@ If installation fails:
       subdirectory called "odpi" containing files. If missing, review the
       section on `Install Using GitHub`_.
 
-
 If importing cx_Oracle fails:
 
     - Do you get the error "``DPI-1047: Oracle Client library cannot be
@@ -160,3 +188,6 @@ If importing cx_Oracle fails:
       <https://oracle.github.io/odpi/doc/installation.html#windows>`__ have been
       installed.
 
+    - If you have both Python 2 and 3 installed, make sure you are
+      using the correct python and pip (or python3 and pip3)
+      executables.