Added user guide documentation.

Author: anthony-tuininga

doc/src/aq.rst doc/src/api_manual/aq.rstdoc/src/aq.rst renamed to doc/src/api_manual/aq.rst

@@ -1,8 +1,10 @@
 .. _aq:
 
-****************
-Advanced Queuing
-****************
+*********************
+Advanced Queuing (AQ)
+*********************
+
+See :ref:`aqusermanual` for more information about using AQ in cx_Oracle.
 
 .. note::
 
@@ -307,4 +309,3 @@ Message Properties
     the dequeue. It will be one of the values :data:`~cx_Oracle.MSG_WAITING`,
     :data:`~cx_Oracle.MSG_READY`, :data:`~cx_Oracle.MSG_PROCESSED` or
     :data:`~cx_Oracle.MSG_EXPIRED`.
-

doc/src/connection.rst doc/src/api_manual/connection.rstdoc/src/connection.rst renamed to doc/src/api_manual/connection.rst

@@ -690,4 +690,3 @@ Connection Object
         If you connect to Oracle Database 18 or higher with client libraries
         12.2 or lower that you will only receive the base version (such as
         18.0.0.0.0) instead of the full version (18.3.0.0.0).
-

doc/src/cursor.rst doc/src/api_manual/cursor.rstdoc/src/cursor.rst renamed to doc/src/api_manual/cursor.rst

@@ -96,6 +96,8 @@ Cursor Object
     positional parameters. The result of the call is the return value of the
     function.
 
+    See :ref:`plsqlfunc` for an example.
+
     .. note::
 
         The DB API definition does not define this method.
@@ -116,6 +118,8 @@ Cursor Object
     possibly new values. Keyword parameters will be included after the
     positional parameters and are not returned as part of the output sequence.
 
+    See :ref:`plsqlproc` for an example.
+
     .. note::
 
         The DB API definition does not allow for keyword parameters.
@@ -152,14 +156,16 @@ Cursor Object
 
 .. method:: Cursor.execute(statement, [parameters], \*\*keywordParameters)
 
-    Execute a statement against the database. Parameters may be passed as a
-    dictionary or sequence or as keyword parameters. If the parameters are a
-    dictionary, the values will be bound by name and if the parameters are a
-    sequence the values will be bound by position. Note that if the values are
-    bound by position, the order of the variables is from left to right as they
-    are encountered in the statement and SQL statements are processed
-    differently than PL/SQL statements. For this reason, it is generally
-    recommended to bind parameters by name instead of by position.
+    Execute a statement against the database.  See :ref:`sqlexecution`.
+
+    Parameters may be passed as a dictionary or sequence or as keyword
+    parameters. If the parameters are a dictionary, the values will be bound by
+    name and if the parameters are a sequence the values will be bound by
+    position. Note that if the values are bound by position, the order of the
+    variables is from left to right as they are encountered in the statement
+    and SQL statements are processed differently than PL/SQL statements. For
+    this reason, it is generally recommended to bind parameters by name instead
+    of by position.
 
     Parameters passed as a dictionary are name and value pairs. The name maps
     to the bind variable name used by the statement and the value maps to the
@@ -193,12 +199,14 @@ Cursor Object
 
     Prepare a statement for execution against a database and then execute it
     against all parameter mappings or sequences found in the sequence
-    parameters. The statement is managed in the same way as the
-    :meth:`~Cursor.execute()` method manages it. If the size of the buffers
-    allocated for any of the parameters exceeds 2 GB, you will receive the
-    error "DPI-1015: array size of <n> is too large", where <n> varies with the
-    size of each element being allocated in the buffer. If you receive this
-    error, decrease the number of elements in the sequence parameters.
+    parameters. See :ref:`batchstmnt`.
+
+    The statement is managed in the same way as the :meth:`~Cursor.execute()`
+    method manages it. If the size of the buffers allocated for any of the
+    parameters exceeds 2 GB, you will receive the error "DPI-1015: array size
+    of <n> is too large", where <n> varies with the size of each element being
+    allocated in the buffer. If you receive this error, decrease the number of
+    elements in the sequence parameters.
 
     If there are no parameters, or parameters have previously been bound, the
     number of iterations can be specified as an integer instead of needing to
@@ -252,6 +260,8 @@ Cursor Object
     An exception is raised if the previous call to :meth:`~Cursor.execute()`
     did not produce any result set or no call was issued yet.
 
+    See :ref:`fetching` for an example.
+
 
 .. method:: Cursor.fetchmany([numRows=cursor.arraysize])
 
@@ -267,6 +277,7 @@ Cursor Object
     An exception is raised if the previous call to :meth:`~Cursor.execute()`
     did not produce any result set or no call was issued yet.
 
+    See :ref:`fetching` for an example.
 
 .. method:: Cursor.fetchone()
 
@@ -276,6 +287,7 @@ Cursor Object
     An exception is raised if the previous call to :meth:`~Cursor.execute()`
     did not produce any result set or no call was issued yet.
 
+    See :ref:`fetching` for an example.
 
 .. method:: Cursor.fetchraw([numRows=cursor.arraysize])
 
@@ -387,6 +399,8 @@ Cursor Object
     variable object will be created. If this attribute is None, the value of
     the attribute with the same name on the connection is used instead.
 
+    See :ref:`outputtypehandlers`.
+
     .. note::
 
         This attribute is an extension to the DB API definition.
@@ -556,4 +570,3 @@ Cursor Object
     .. note::
 
         The DB API definition does not define this method.
-

doc/src/lob.rst doc/src/api_manual/lob.rstdoc/src/lob.rst renamed to doc/src/api_manual/lob.rst

@@ -4,6 +4,8 @@
 LOB Objects
 ***********
 
+See :ref:`lobdata` for more information about using LOBs.
+
 .. note::
 
     This object is an extension the DB API. It is returned whenever Oracle
@@ -86,4 +88,3 @@ LOB Objects
     offset will have to be chosen carefully to avoid splitting a character.
     Note that if you want to make the LOB value smaller, you must use the
     :meth:`~LOB.trim()` function.
-

doc/src/module.rst doc/src/api_manual/module.rstdoc/src/module.rst renamed to doc/src/api_manual/module.rst

@@ -36,27 +36,29 @@ Module Interface
         This method is an extension to the DB API definition.
 
 
-.. function:: Connection(user=None, password=None, dsn=None, \
+.. function:: connect(user=None, password=None, dsn=None, mode=cx_Oracle.DEFAULT_AUTH, \
+        handle=0, pool=None, threaded=False, events=False, cclass=None, \
+        purity=cx_Oracle.ATTR_PURITY_DEFAULT, newpassword=None, \
+        encoding=None, nencoding=None, edition=None, appcontext=[], tag=None, \
+        matchanytag=None, shardingkey=[], supershardingkey=[])
+    Connection(user=None, password=None, dsn=None, \
         mode=cx_Oracle.DEFAULT_AUTH, handle=0, pool=None, threaded=False, \
         events=False, cclass=None, purity=cx_Oracle.ATTR_PURITY_DEFAULT, \
         newpassword=None, encoding=None, nencoding=None, edition=None, \
         appcontext=[], tag=None, matchanytag=False, shardingkey=[], \
         supershardingkey=[])
-    connect(user=None, password=None, dsn=None, mode=cx_Oracle.DEFAULT_AUTH, \
-        handle=0, pool=None, threaded=False, events=False, cclass=None, \
-        purity=cx_Oracle.ATTR_PURITY_DEFAULT, newpassword=None, \
-        encoding=None, nencoding=None, edition=None, appcontext=[], tag=None, \
-        matchanytag=None, shardingkey=[], supershardingkey=[])
 
     Constructor for creating a connection to the database. Return a
     :ref:`connection object <connobj>`. All parameters are optional and can be
-    specified as keyword parameters.
+    specified as keyword parameters.  See :ref:`connhandling` information about
+    connections.
 
     The dsn (data source name) is the TNS entry (from the Oracle names server
     or tnsnames.ora file) or is a string like the one returned from
     :meth:`~cx_Oracle.makedsn()`. If only one parameter is passed, a connect
     string is assumed which is to be of the format ``user/password@dsn``, the
-    same format accepted by Oracle applications such as SQL\*Plus.
+    same format accepted by Oracle applications such as SQL\*Plus.  See
+    :ref:`connstr` for more information.
 
     If the mode is specified, it must be one of the
     :ref:`connection authorization modes<connection-authorization-modes>`
@@ -140,7 +142,7 @@ Module Interface
 
 .. function:: Cursor(connection)
 
-    Constructor for creating a cursor.  Return a new 
+    Constructor for creating a cursor.  Return a new
     :ref:`cursor object <cursorobj>` using the connection.
 
     .. note::
@@ -187,6 +189,8 @@ Module Interface
     like `Application Continuity <https://www.oracle.com/pls/topic/lookup?
     ctx=dblatest&id=GUID-A8DD9422-2F82-42A9-9555-134296416E8F>`__.
 
+    See :ref:`connpool` for information on connection pooling.
+
     Session pooling creates a pool of available connections to the
     database, allowing applications to acquire a connection very quickly.
     It is of primary use in a server where connections are requested
@@ -747,6 +751,8 @@ for subscriptions created by the :meth:`Connection.subscribe()` method.
     being started up.
 
 
+.. _cqn-operation-codes:
+
 Operation Codes
 ---------------
 
@@ -894,6 +900,8 @@ method.
     events.
 
 
+.. _subscr-namespaces:
+
 Subscription Namespaces
 -----------------------
 
@@ -912,6 +920,8 @@ method.
     change notification messages are to be sent. This is the default value.
 
 
+.. _subscr-protocols:
+
 Subscription Protocols
 ----------------------
 
@@ -947,6 +957,8 @@ values for the protocol parameter of the :meth:`Connection.subscribe()` method.
     supported.
 
 
+.. _subscr-qos:
+
 Subscription Quality of Service
 -------------------------------
 
@@ -986,6 +998,8 @@ or more of these values can be OR'ed together.
     or deleted rows should be included in the message objects that are sent.
 
 
+.. _types:
+
 Types
 =====
 
@@ -1258,6 +1272,8 @@ Exceptions
     supported by the database. It is a subclass of DatabaseError.
 
 
+.. _exchandling:
+
 Exception handling
 ==================
 
@@ -1317,4 +1333,3 @@ This allows you to use the exceptions for example in the following way:
         error, = exc.args
         print("Oracle-Error-Code:", error.code)
         print("Oracle-Error-Message:", error.message)
-

doc/src/objecttype.rst doc/src/api_manual/object_type.rstdoc/src/objecttype.rst renamed to doc/src/api_manual/object_type.rst

@@ -49,7 +49,7 @@ Object Type Objects
 
 
 Object Objects
-==============
+--------------
 
 .. note::
 
@@ -71,6 +71,8 @@ Object Objects
     Return a dictionary where the collection's indexes are the keys and the
     elements are its values.
 
+    .. versionadded:: 7.0
+
 
 .. method:: Object.aslist()
 
@@ -149,4 +151,3 @@ Object Objects
 .. method:: Object.trim(num)
 
     Remove the specified number of elements from the end of the collection.
-

doc/src/session_pool.rst doc/src/api_manual/session_pool.rstdoc/src/session_pool.rst renamed to doc/src/api_manual/session_pool.rst

@@ -10,6 +10,8 @@ SessionPool Object
 
     Connection pooling in cx_Oracle is handled by SessionPool objects.
 
+    See :ref:`connpool` for information on connection pooling.
+
 
 .. method:: SessionPool.acquire(user=None, password=None, cclass=None, \
         purity=cx_Oracle.ATTR_PURITY_DEFAULT, tag=None, matchanytag=False, \
@@ -185,4 +187,3 @@ SessionPool Object
     :data:`cx_Oracle.SPOOL_ATTRVAL_TIMEDWAIT`.
 
     .. versionadded:: 6.4
-

doc/src/soda.rst doc/src/api_manual/soda.rstdoc/src/soda.rst renamed to doc/src/api_manual/soda.rst

@@ -4,9 +4,12 @@
 SODA
 ****
 
-An overview of Simple Oracle Document Access (SODA) can be found
-`here
-<https://docs.oracle.com/en/database/oracle/simple-oracle-document-access>`__.
+`Oracle Database Simple Oracle Document Access (SODA)
+<https://docs.oracle.com/en/database/oracle/simple-oracle-document-access>`__
+allows documents to be inserted, queried, and retrieved from Oracle Database
+using a set of NoSQL-style cx_Oracle methods.
+
+See :ref:`sodausermanual` for a cx_Oracle example.
 
 SODA requires Oracle Client 18.3 or higher and Oracle Database 18.1 and higher.
 The role SODA_APP must be granted to the user.
@@ -110,7 +113,7 @@ SODA Collection Object
 .. note::
 
     This object is an extension the DB API. It is used to represent SODA
-    collections and is created by methods 
+    collections and is created by methods
     :meth:`SodaDatabase.createCollection()` and
     :meth:`SodaDatabase.openCollection()`.
 
@@ -520,4 +523,3 @@ SODA Operation Object
     criteria can be specified by chaining methods together.
 
     .. versionadded:: 7.0
-

doc/src/subscription.rst doc/src/api_manual/subscription.rstdoc/src/subscription.rst renamed to doc/src/api_manual/subscription.rst

@@ -98,7 +98,7 @@ Subscription Object
 .. _msgobjects:
 
 Message Objects
-===============
+---------------
 
 .. note::
 
@@ -177,7 +177,7 @@ Message Objects
 
 
 Message Table Objects
-=====================
+---------------------
 
 .. note::
 
@@ -206,7 +206,7 @@ Message Table Objects
 
 
 Message Row Objects
-===================
+-------------------
 
 .. note::
 
@@ -227,19 +227,19 @@ Message Row Objects
 
 
 Message Query Objects
-=====================
+---------------------
 
 .. note::
 
     This object is created internally for each query result set changed when
     notification is received and is found in the queries attribute of message
     objects.
-   
+
 
 .. attribute:: MessageQuery.id
 
     This read-only attribute returns the query id of the query for which the
-    result set changed. The value will match the value returned by 
+    result set changed. The value will match the value returned by
     Subscription.registerquery when the related query was registered.
 
 
@@ -255,4 +255,3 @@ Message Query Objects
     This read-only attribute returns a list of message table objects that give
     information about the table changes that caused the query result set to
     change for this notification.
-

doc/src/variable.rst doc/src/api_manual/variable.rstdoc/src/variable.rst renamed to doc/src/api_manual/variable.rst

@@ -81,4 +81,3 @@ Variable Objects
     positions in the variable as a list. This is the equivalent of calling
     :meth:`~Variable.getvalue()` for each valid position and the length will
     correspond to the value of the :attr:`~Variable.actualElements` attribute.
-