Tweak documentation and README files.

Author: anthony-tuininga

doc/src/user_guide/installation.rst

@@ -17,7 +17,7 @@ To use cx_Oracle 8 with Python and Oracle Database you need:
   <https://www.oracle.com/database/technologies/instant-client.html>`__,
   or those included in Oracle Database if Python is on the same
   machine as the database.  Oracle client libraries versions 19, 18, 12,
-  and 11.2 are supported on Linux, Windows and macOS.  Users have
+  and 11.2 are supported on Linux, Windows and macOS (Intel x86).  Users have
   also reported success with other platforms.  Use the latest client possible:
   Oracle's standard client-server version interoperability allows connection to
   both older and newer databases.
@@ -571,8 +571,8 @@ Python architecture.
    Alternatively, pass ``config_dir`` to :meth:`~cx_Oracle.init_oracle_client()`
    as shown in the previous section, or set ``TNS_ADMIN`` to the directory name.
 
-Installing cx_Oracle on macOS
-=============================
+Installing cx_Oracle on macOS (Intel x86)
+=========================================
 
 Install Python
 --------------
@@ -582,6 +582,8 @@ entitlements and will fail to load Oracle client libraries.  Instead use
 `Homebrew <https://brew.sh>`__ or `Python.org
 <https://www.python.org/downloads>`__.
 
+A C compiler is needed, for example Xcode and its command line tools.
+
 Install cx_Oracle
 -----------------
 
@@ -591,6 +593,7 @@ package to install cx_Oracle from `PyPI
 
 .. code-block:: shell
 
+    export ARCHFLAGS="-arch x86_64"
     python -m pip install cx_Oracle --upgrade
 
 The ``--user`` option may be useful, if you don't have permission to write to

samples/README.md

@@ -1,4 +1,6 @@
-This directory contains samples for cx_Oracle.
+# cx_Oracle Examples
+
+This directory contains samples for [cx_Oracle][6].  Documentation is [here][7].
 
 1. The schemas and SQL objects that are referenced in the samples can be
    created by running the Python script [SetupSamples.py][1]. The script
@@ -39,3 +41,5 @@ This directory contains samples for cx_Oracle.
 [3]: https://github.com/oracle/python-cx_Oracle/blob/master/samples/sql/SetupSamples.sql
 [4]: https://github.com/oracle/python-cx_Oracle/blob/master/samples/DropSamples.py
 [5]: https://github.com/oracle/python-cx_Oracle/blob/master/samples/sql/DropSamples.sql
+[6]: https://oracle.github.io/python-cx_Oracle/
+[7]: http://cx-oracle.readthedocs.org/en/latest/index.html

test/README.md

@@ -1,46 +1,53 @@
 This directory contains the test suite for cx_Oracle.
 
-1. The schemas and SQL objects that are referenced in the test suite can be
-   created by running the Python script [SetupTest.py][1]. The script requires
-   administrative privileges and will prompt for these credentials as well as
-   the names of the schemas that will be created, unless a number of
-   environment variables are set as documented in the Python script
-   [TestEnv.py][2]. Run the script using the following command:
+1.  The schemas and SQL objects that are referenced in the test suite can be
+    created by running the Python script [SetupTest.py][1]. The script requires
+    administrative privileges and will prompt for these credentials as well as
+    the names of the schemas that will be created, unless a number of
+    environment variables are set, as documented in the Python script
+    [test_env.py][2]. Run the script using the following command:
 
-       python SetupTest.py
+        python SetupTest.py
 
-   Alternatively, the [SQL script][3] can be run directly via SQL\*Plus, which
-   will always prompt for the names of the schemas that will be created. Run
-   the script using the following command:
+    Alternatively, the [SQL script][3] can be run directly via SQL\*Plus, which
+    will always prompt for the names of the schemas that will be created. Run
+    the script using the following command:
 
-       sqlplus system/systempassword@hostname/servicename @sql/SetupTest.sql
+        sqlplus system/systempassword@hostname/servicename @sql/SetupTest.sql
 
-2. Run the test suite by issuing the following command in the top-level
-   directory of your cx_Oracle installation:
+2.  Run the test suite by issuing the following command in the top-level
+    directory of your cx_Oracle installation:
 
-       tox
+        tox
 
-   Alternatively, you can run the test suite directly within this directory:
+    This will build the module in an independent environment and run the test
+    suite using the module that was just built in that environment.
+    Alternatively, you can use the currently installed build of cx_Oracle and
+    run the following command instead:
 
-       python TestEnv.py
+        python -m unittest discover -v -s test
 
-3. After running the test suite, the schemas can be dropped by running the
-   Python script [DropTest.py][4]. The script requires administrative
-   privileges and will prompt for these credentials as well as the names of the
-   schemas that will be dropped, unless a number of environment variables are
-   set as documented in the Python script [TestEnv.py][2]. Run the script using
-   the following command:
+    You may also run each of the test scripts independently, as in:
 
-       python DropTest.py
+        python test_1000_module.py
 
-   Alternatively, the [SQL script][5] can be run directly via SQL\*Plus, which
-   will always prompt for the names of the schemas that will be dropped. Run
-   the script using the following command:
+3.  After running the test suite, the schemas can be dropped by running the
+    Python script [DropTest.py][4]. The script requires administrative
+    privileges and will prompt for these credentials as well as the names of
+    the schemas that will be dropped, unless a number of environment variables
+    are set, as documented in the Python script [test_env.py][2]. Run the
+    script using the following command:
 
-       sqlplus system/systempassword@hostname/servicename @sql/DropTest.sql
+        python DropTest.py
+
+    Alternatively, the [SQL script][5] can be run directly via SQL\*Plus, which
+    will always prompt for the names of the schemas that will be dropped. Run
+    the script using the following command:
+
+        sqlplus system/systempassword@hostname/servicename @sql/DropTest.sql
 
 [1]: https://github.com/oracle/python-cx_Oracle/blob/master/test/SetupTest.py
-[2]: https://github.com/oracle/python-cx_Oracle/blob/master/test/TestEnv.py
+[2]: https://github.com/oracle/python-cx_Oracle/blob/master/test/test_env.py
 [3]: https://github.com/oracle/python-cx_Oracle/blob/master/test/sql/SetupTest.sql
 [4]: https://github.com/oracle/python-cx_Oracle/blob/master/test/DropTest.py
 [5]: https://github.com/oracle/python-cx_Oracle/blob/master/test/sql/DropTest.sql