Documentation improvements.

Author: anthony-tuininga

doc/src/index.rst

@@ -9,7 +9,7 @@ Database. It conforms to the `Python Database API v2.0 Specification
 additions and a couple of exclusions.
 
 This module is currently tested with Python 3.6, 3.7, 3.8, 3.9, 3.10 and 3.11
-against Oracle Database 23c, 21c, 19c, 18c, 12c, and 11.2.
+against Oracle Database 23c, 21c, 19c, 18c, 12c, and 11gR2.
 
 **python-oracledb** is distributed under an open-source
 :ref:`license <license>`. Changes in python-oracledb releases can be found in

doc/src/release_notes.rst

@@ -46,20 +46,20 @@ Thin Mode Changes
 #)  Fixed bug when an output type handler is used and the value of
     cursor.prefetchrows exceeds cursor.arraysize
     (`issue 173 <https://github.com/oracle/python-oracledb/issues/173>`__).
-#)  Fixed bug when an AC replay context is returned during connection to the
-    database
+#)  Fixed bug when an Application Continuity replay context is returned during
+    connection to the database
     (`issue 176 <https://github.com/oracle/python-oracledb/issues/176>`__).
 
 Thick Mode Changes
 ++++++++++++++++++
 
-#)  Added function :meth:`SodaCollection.getIndexes()` for geting the indexes
+#)  Added function :meth:`SodaCollection.getIndexes()` for getting the indexes
     on a SODA collection.
+#)  Relaxed restriction for end-to-end tracing string connection
+    attributes. These values can now be set to the value ``None`` which will be
+    treated the same as an empty string.
 #)  Fixed bug when using external authentication with an Easy Connect
     connection string.
-#)  Relaxed restriction for end-to-end string connection attributes. These
-    values can be set to the value ``None`` which will be treated the same as
-    an empty string.
 #)  Fixed memory leak when accessing objects embedded within other objects.
 
 Common Changes
@@ -76,21 +76,20 @@ Common Changes
     Oracle Database instance name associated with the connection. This is the
     same value as the SQL expression
     ``sys_context('userenv', 'instance_name')``.
-#)  Added support for automatically retrying a query if the error
-    ``ORA-00932: inconsistent data types`` is raised (which can occur if a
-    table or view is recreated with a data type that is incompatible with
-    the column's previous data type).
-#)  Added support for the embedded OIDs found in SODA documents in Oracle
-    Database 23c.
+#)  Added support for relational queries on the underlying tables of SODA
+    collections created in Oracle Database 23c if they contain JSON documents
+    with embedded OIDs.
+#)  Automatically retry a query if the error ``ORA-00932: inconsistent data
+    types`` is raised (which can occur if a table or view is recreated with a
+    data type that is incompatible with the column's previous data type).
 #)  The ``repr()`` value of the DbObject class now shows the string "DbObject"
     instead of the string "Object" for consistency with the name of the class
     and the other ``repr()`` values for DbObjectType and DbObjectAttr.
 #)  Fixed bug when binding sequences other than lists and tuples
     (`issue 205 <https://github.com/oracle/python-oracledb/issues/205>`__).
 #)  Added support for using the Cython 3.0 release
     (`issue 204 <https://github.com/oracle/python-oracledb/issues/204>`__).
-#)  Improved test suite.
-
+#)  Improved test suite and documentation.
 
 oracledb 1.3.2 (June 2023)
 --------------------------

doc/src/user_guide/initialization.rst

@@ -253,11 +253,12 @@ parameter.
 
     oracledb.init_oracle_client()
 
-Oracle Client libraries are looked for in the operating system library
-search path, such as configured with ``ldconfig`` or set in the environment
-variable ``LD_LIBRARY_PATH``.  On some UNIX platforms an OS specific
-equivalent, such as ``LIBPATH`` or ``SHLIB_PATH``, is used instead of
-``LD_LIBRARY_PATH``.
+Oracle Client libraries are looked for in the operating system library search
+path, such as configured with ``ldconfig`` or set in the environment variable
+``LD_LIBRARY_PATH``.  Web servers and other daemons commonly reset environment
+variables so using ``ldconfig`` is generally preferred instead.  On some UNIX
+platforms an OS specific equivalent, such as ``LIBPATH`` or ``SHLIB_PATH``, is
+used instead of ``LD_LIBRARY_PATH``.
 
 If libraries are not found in the system library search path, then libraries
 in ``$ORACLE_HOME/lib`` will be used.  Note that the environment variable

doc/src/user_guide/installation.rst

@@ -259,8 +259,12 @@ To use python-oracledb Thick mode with Oracle Instant Client zip files:
   - `x86 32-bit <https://www.oracle.com/database/technologies/instant-client/linux-x86-32-downloads.html>`__
   - `ARM (aarch64) 64-bit <https://www.oracle.com/database/technologies/instant-client/linux-arm-aarch64-downloads.html>`__
 
-  The latest version is recommended. Oracle Instant Client 21 will connect to
-  Oracle Database 12.1 or later.
+  Oracle Database 19c is a Long Term Support Release whereas Oracle Database
+  21c is an Innovation Release.  It is recommended to keep up to date with the
+  latest Oracle Instant Client release updates of your desired major version.
+
+  Oracle Instant Client 19c will connect to Oracle Database 11.2 or later.
+  Oracle Instant Client 21c will connect to Oracle Database 12.1 or later.
 
 2. Unzip the package into a single directory that is accessible to your
    application. For example:
@@ -299,6 +303,10 @@ To use python-oracledb Thick mode with Oracle Instant Client zip files:
 
        export LD_LIBRARY_PATH=/opt/oracle/instantclient_21_6:$LD_LIBRARY_PATH
 
+  Make sure this is set in each shell that invokes Python.  Web servers and
+  other daemons commonly reset environment variables so using ``ldconfig`` is
+  generally preferred instead.
+
 5. If you use optional Oracle configuration files such as ``tnsnames.ora``,
    ``sqlnet.ora``, or ``oraaccess.xml`` with Instant Client, then put the files
    in an accessible directory, for example in
@@ -340,8 +348,12 @@ To use python-oracledb with Oracle Instant Client RPMs:
   - `Instant Client RPMs for Oracle Linux ARM (aarch64) 8 <https://yum.oracle.com/repo/OracleLinux/OL8/oracle/instantclient/aarch64/index.html>`__
   - `Instant Client RPMs for Oracle Linux ARM (aarch64) 7 <https://yum.oracle.com/repo/OracleLinux/OL7/oracle/instantclient/aarch64/index.html>`__
 
-  The latest version is recommended.  Oracle Instant Client 21 will connect to
-  Oracle Database 12.1 or later.
+  Oracle Database 19c is a Long Term Support Release whereas Oracle Database
+  21c is an Innovation Release.  It is recommended to keep up to date with the
+  latest Oracle Instant Client release updates of your desired major version.
+
+  Oracle Instant Client 19c will connect to Oracle Database 11.2 or later.
+  Oracle Instant Client 21c will connect to Oracle Database 12.1 or later.
 
 2. Install the downloaded RPM with sudo or as the root user. For example:
 
@@ -373,6 +385,9 @@ To use python-oracledb with Oracle Instant Client RPMs:
 
        export LD_LIBRARY_PATH=/usr/lib/oracle/18.5/client64/lib:$LD_LIBRARY_PATH
 
+  Web servers and other daemons commonly reset environment variables so using
+  ``ldconfig`` is generally preferred instead.
+
 4. If you use optional Oracle configuration files such as ``tnsnames.ora``,
    ``sqlnet.ora`` or ``oraaccess.xml`` with Instant Client, then put the files
    in an accessible directory, for example in
@@ -938,10 +953,10 @@ If using python-oracledb fails:
 
   - On Linux, check if the ``LD_LIBRARY_PATH`` environment variable contains
     the Oracle Client library directory.  Some environments such as web servers
-    reset environment variables.  If you are using Oracle Instant Client, a
-    preferred alternative to ``LD_LIBRARY_PATH`` is to ensure that a file in
-    the ``/etc/ld.so.conf.d`` directory contains the path to the Instant Client
-    directory, and then run ``ldconfig``.
+    and daemons reset environment variables.  If you are using Oracle Instant
+    Client, a preferred alternative to ``LD_LIBRARY_PATH`` is to ensure that a
+    file in the ``/etc/ld.so.conf.d`` directory contains the path to the
+    Instant Client directory, and then run ``ldconfig``.
 
 - If you get the error ``DPY-3010: connections to this database server
   version are not supported by python-oracledb in thin mode`` when