Further doc improvements.

Author: anthony-tuininga

doc/README.md

@@ -1,16 +1,18 @@
 Sphinx is used to generate the HTML for the python-oracledb documentation.
 
-The generated python-oracledb documentation is at https://python-oracledb.readthedocs.io/
+The generated python-oracledb documentation is at
+https://python-oracledb.readthedocs.io/
 
 This directory contains the documentation source.  It is written using reST
 (re-Structured Text). The source files are processed using Sphinx and can be
 turned into HTML, PDF or ePub documentation.
 
-If you wish to build documentation yourself, install Sphinx.  It is available
-on many Linux distributions as a pre-built package. You can also install it
-using the Python package manager "pip", for example::
+If you wish to build documentation yourself, install Sphinx and the Read the
+Docs theme.  Sphinx is available on many Linux distributions as a pre-built
+package. You can also install Sphinx and the Read the Docs theme using the
+Python package manager "pip", for example::
 
-    python -m pip install Sphinx
+    python -m pip install -r requirements.txt
 
 For more information on Sphinx, please visit this page:
 

doc/requirements.txt

@@ -1 +1,2 @@
-sphinx==4.1.2
+sphinx>=4.2.0
+sphinx-rtd-theme

doc/src/api_manual/connect_param.rst

@@ -37,10 +37,10 @@ ConnectParams Methods
     https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
     server_type=None, cclass=None, purity=None, expire_time=None, retry_count=None, \
     retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, \
-    ssl_server_cert_dn=None, wallet_location=None, events=None, mode=None, \
-    disable_oob=None, stmtcachesize=None, edition=None, tag=None, matchanytag=None, \
-    config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-    handle=None)
+    ssl_server_cert_dn=None, wallet_location=None, events=None, externalauth=None, \
+    mode=None, disable_oob=None, stmtcachesize=None, edition=None, tag=None, \
+    matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], \
+    debug_jdwp=None, handle=None)
 
   Sets one or more of the parameters.
 
@@ -127,6 +127,18 @@ ConnectParams Attributes
 
   This attribute is supported in the python-oracledb Thin and Thick modes.
 
+.. attribute:: ConnectParams.externalauth
+
+  This read-only attribute is a boolean that specifies whether external
+  authentication should be used. The default value is False.
+
+  For standalone connections, external authentication occurs when the
+  ``user`` and ``password`` attributes are not used. If these attributes,
+  are not used, you can optionally set the ``externalauth`` attribute to
+  True, which may aid code auditing.
+
+  This attribute is only supported in the python-oracledb Thick mode.
+
 .. attribute:: ConnectParams.host
 
   This read-only attribute is a string that returns the name or IP address of

doc/src/api_manual/module.rst

@@ -49,13 +49,14 @@ Oracledb Methods
 
 .. function:: connect(dsn=None, pool=None, conn_class=None, params=None, user=None, \
     proxy_user=None, password=None, newpassword=None, wallet_password=None, \
-    host=None, port=None, protocol=None, https_proxy=None, https_proxy_port=None, \
-    service_name=None, sid=None, server_type=None, cclass=None, purity=None, \
-    expire_time=None, retry_count=None, retry_delay=None, tcp_connect_timeout=None, \
-    ssl_server_dn_match=None, ssl_server_cert_dn=None, wallet_location=None, \
-    events=None, mode=None, disable_oob=None, stmtcachesize=None, edition=None, \
-    tag=None, matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], \
-    supershardingkey=[], debug_jdwp=None, handle=None)
+    host=None, port=1521, protocol="tcp", https_proxy=None, https_proxy_port=0, \
+    service_name=None, sid=None, server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, \
+    expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, \
+    ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, \
+    events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
+    stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, matchanytag=False, \
+    config_dir=oracledb.defaults.config_dir, appcontext=[], shardingkey=[], supershardingkey=[], \
+    debug_jdwp=None, handle=0)
 
     Constructor for creating a connection to the database. Returns a
     :ref:`Connection Object <connobj>`. All parameters are optional and can be
@@ -216,10 +217,18 @@ Oracledb Methods
     query notification and high availability event notifications. The default
     value is False.
 
+    The ``externalauth`` parameter is a boolean that specifies whether external
+    authentication should be used. This value is only used in the python-oracledb
+    Thick mode. The default value is False. For standalone connections,
+    external authentication occurs when the ``user`` and ``password`` attributes
+    are not used. If these attributes are not used, you can optionally set the
+    ``externalauth`` attribute to True, which may aid code auditing.
+
     If the ``mode`` parameter is specified, it must be one of the
     :ref:`connection authorization modes <connection-authorization-modes>`
     which are defined at the module level. This value is used in both the
-    python-oracledb Thin and Thick modes.The default value is 0.
+    python-oracledb Thin and Thick modes. The default value is
+    :data:`oracledb.AUTH_MODE_DEFAULT`.
 
     The ``disable_oob`` parameter is expected to be a boolean that indicates
     whether out-of-band breaks should be disabled. This value is only used
@@ -273,17 +282,17 @@ Oracledb Methods
     PowerBuilder) which has already made the connection. The connection thus
     created should *never* be used after the source handle has been closed or
     destroyed. This value is only used in the python-oracledb Thick mode.  It
-    should be used with extreme caution.
+    should be used with extreme caution. The default value is 0.
 
 .. function:: ConnectParams(user=None, proxy_user=None, password=None, \
-    newpassword=None, wallet_password=None, host=None, port=None, protocol=None, \
-    https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
-    server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=None, \
-    retry_count=None, retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, \
-    ssl_server_cert_dn=None, wallet_location=None, events=None, mode=None, \
-    disable_oob=None, stmtcachesize=None, edition=None, tag=None, matchanytag=None, \
-    config_dir=None, appcontext=None, shardingkey=None, supershardingkey=None, \
-    debug_jdwp=None, handle=None)
+    newpassword=None, wallet_password=None, host=None, port=1521, protocol="tcp", \
+    https_proxy=None, https_proxy_port=0, service_name=None, sid=None, \
+    server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, expire_time=0, \
+    retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, ssl_server_dn_match=True, \
+    ssl_server_cert_dn=None, wallet_location=None, events=False, externalauth=False, \
+    mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, stmtcachesize=oracledb.defaults.stmtcachesize, \
+    edition=None, tag=None, matchanytag=False, config_dir=oracledb.defaults.config_dir, \
+    appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0)
 
     Contains all the parameters that can be used to establish a connection to the database.
 
@@ -407,9 +416,16 @@ Oracledb Methods
     query notification and high availability event notifications. The default
     value is False.
 
+    The ``externalauth`` parameter is a boolean that specifies whether external
+    authentication should be used. This value is only used in the python-oracledb
+    Thick mode. The default value is False. For standalone connections,
+    external authentication occurs when the ``user`` and ``password`` attributes
+    are not used. If these attributes are not used, you can optionally set the
+    ``externalauth`` attribute to True, which may aid code auditing.
+
     The ``mode`` parameter is expected to be an integer that identifies the
     authorization mode to use. This value is used in both the python-oracledb
-    Thin and Thick modes.The default value is 0.
+    Thin and Thick modes.The default value is :data:`oracledb.AUTH_MODE_DEFAULT`.
 
     The ``disable_oob`` parameter is expected to be a boolean that indicates
     whether out-of-band breaks should be disabled. This value is only used
@@ -463,25 +479,26 @@ Oracledb Methods
 
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
-    python-oracledb Thick mode.  It should be used with extreme caution.
+    python-oracledb Thick mode.  It should be used with extreme caution. The
+    default value is 0.
 
 
 .. function:: create_pool(dsn=None, pool_class=oracledb.ConnectionPool, \
-        params=None, min=1, max=2, increment=1, \
-        connectiontype=oracledb.Connection, getmode=None, homogeneous=None, \
-        externalauth=None, timeout=0, wait_timeout=0, max_lifetime_session=0, \
-        session_callback=None, max_sessions_per_shard=0, \
-        soda_metadata_cache=False, ping_interval=60, user=None, \
-        proxy_user=None, password=None, newpassword=None, \
+        params=None, min=1, max=2, increment=1, connectiontype=oracledb.Connection, \
+        getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \
+        wait_timeout=0, max_lifetime_session=0, session_callback=None, \
+        max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \
+        user=None, proxy_user=None, password=None, newpassword=None, \
         wallet_password=None, host=None, port=1521, protocol="tcp", \
-        https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
+        https_proxy=None, https_proxy_port=0, service_name=None, sid=None, \
         server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, \
-        expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60, \
+        expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, \
         ssl_server_dn_match=True, ssl_server_cert_dn=None, \
-        wallet_location=None, events=False, mode=oracledb.AUTH_MODE_DEFAULT, \
-        disable_oob=None, stmtcachesize=None, edition=None, tag=None, \
-        matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], \
-        supershardingkey=[], debug_jdwp=None, handle=0)
+        wallet_location=None, events=False, externalauth=False, \
+        mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
+        stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, \
+        matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], \
+        shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0)
 
     Creates a connection pool with the supplied parameters and returns the
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
@@ -508,7 +525,7 @@ Oracledb Methods
     ``params`` parameter object. Similar precedence rules also apply to other
     values.
 
-    The ``user``, ``password`` and ``dsn`` parameters are the same as for
+    The ``user``, ``password``, and ``dsn`` parameters are the same as for
     :meth:`oracledb.connect()`.
 
     The ``pool_class`` parameter is expected to be a
@@ -529,10 +546,12 @@ Oracledb Methods
     behavior. A fixed pool size where ``min`` equals ``max`` is
     :ref:`recommended <connpoolsize>` to help prevent connection storms and to
     help overall system stability. The ``min`` parameter is the number of
-    connections opened when the pool is created. The ``increment`` is the
-    number of connections that are opened whenever a connection request exceeds
-    the number of currently open connections. The ``max`` parameter is the
-    maximum number of connections that can be open in the connection pool.
+    connections opened when the pool is created. The default value of the
+    ``min`` parameter is 1. The ``increment`` parameter is the number of connections
+    that are opened whenever a connection request exceeds the number of currently
+    open connections. The default value of the ``increment`` parameter is 1.
+    The ``max`` parameter is the maximum number of connections that can be open
+    in the connection pool. The default value of the ``max`` parameter is 2.
 
     If the ``connectiontype`` parameter is specified, all calls to
     :meth:`ConnectionPool.acquire()` will create connection objects of that
@@ -549,9 +568,6 @@ Oracledb Methods
     connections are homogeneous (same user) or heterogeneous (multiple
     users). The default value is True.
 
-    The ``externalauth`` parameter is a boolean that determines whether to use
-    external authentication. The default value is False.
-
     The ``timeout`` parameter is the length of time (in seconds) that a
     connection may remain idle in the pool before it is terminated. If the
     value of this parameter is 0, then the connections are never terminated.
@@ -697,10 +713,15 @@ Oracledb Methods
     query notification and high availability event notifications. The default
     value is False.
 
+    The ``externalauth`` parameter is a boolean that determines whether to use
+    external authentication. This value is only used in the python-oracledb Thick
+    mode. The default value is False.
+
     If the ``mode`` parameter is specified, it must be one of the
     :ref:`connection authorization modes <connection-authorization-modes>`
     which are defined at the module level. This value is used in both the
-    python-oracledb Thin and Thick modes.The default value is 0.
+    python-oracledb Thin and Thick modes.The default value is
+    :data:`oracledb.AUTH_MODE_DEFAULT`.
 
     The ``disable_oob`` parameter is expected to be a boolean that indicates
     whether out-of-band breaks should be disabled. This value is only used
@@ -757,7 +778,7 @@ Oracledb Methods
     PowerBuilder) which has already made the connection. The connection thus
     created should *never* be used after the source handle has been closed or
     destroyed. This value is only used in the python-oracledb Thick mode. It
-    should be used with extreme caution.
+    should be used with extreme caution. The deault value is 0.
 
     In the python-oracledb Thick mode, connection pooling is handled by
     Oracle's `Session pooling <https://www.oracle.com/pls/topic/lookup?
@@ -849,16 +870,16 @@ Oracledb Methods
         This method is an extension to the DB API definition.
 
 .. function:: PoolParams(min=1, max=2, increment=1, connectiontype=None, \
-    getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, externalauth=False, \
-    timeout=0, wait_timeout=0, max_lifetime_session=0, session_callback=None, \
+    getmode=oracledb.POOL_GETMODE_WAIT, homogeneous=True, timeout=0, \
+    wait_timeout=0, max_lifetime_session=0, session_callback=None, \
     max_sessions_per_shard=0, soda_metadata_cache=False, ping_interval=60, \
     user=None, proxy_user=Nonde, password=None, newpassword=None, \
     wallet_password=None, host=None, port=1521, protocol="tcp", \
-    https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
+    https_proxy=None, https_proxy_port=0, service_name=None, sid=None, \
     server_type=None, cclass=None, purity=oracledb.PURITY_DEFAULT, \
-    expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60, \
+    expire_time=0, retry_count=0, retry_delay=0, tcp_connect_timeout=60.0, \
     ssl_server_dn_match=True, ssl_server_cert_dn=None, wallet_location=None, \
-    events=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
+    events=False, externalauth=False, mode=oracledb.AUTH_MODE_DEFAULT, disable_oob=False, \
     stmtcachesize=oracledb.defaults.stmtcachesize, edition=None, tag=None, \
     matchanytag=False, config_dir=oracledb.defaults.config_dir, appcontext=[], \
     shardingkey=[], supershardingkey=[], debug_jdwp=None, handle=0)
@@ -893,9 +914,6 @@ Oracledb Methods
     connections are homogeneous (same user) or heterogeneous (multiple users).
     The default value is True.
 
-    The ``externalauth`` parameter is a boolean that determines whether to use
-    external authentication. The default value is False.
-
     The ``timeout`` parameter is the length of time (in seconds) that a
     connection may remain idle in the pool before it is terminated. If the
     value of this parameter is 0, then the connections are never terminated.
@@ -1043,6 +1061,10 @@ Oracledb Methods
     the file, cwallet.sso. This value is used in both the python-oracledb Thin
     and Thick modes.
 
+    The ``externalauth`` parameter is a boolean that determines whether to use
+    external authentication. This value is only used in the python-oracledb Thick
+    mode. The default value is False.
+
     The ``events`` parameter is expected to be a boolean that specifies whether
     the events mode should be enabled. This value is only used in the
     python-oracledb Thick mode. This parameter is needed for continuous
@@ -1051,7 +1073,7 @@ Oracledb Methods
 
     The ``mode`` parameter is expected to be an integer that identifies the
     authorization mode to use. This value is used in both the python-oracledb
-    Thin and Thick modes.The default value is 0.
+    Thin and Thick modes.The default value is :data:`oracledb.AUTH_MODE_DEFAULT`.
 
     The ``disable_oob`` parameter is expected to be a boolean that indicates
     whether out-of-band breaks should be disabled. This value is only used
@@ -1107,7 +1129,8 @@ Oracledb Methods
 
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
-    python-oracledb Thick mode. It should be used with extreme caution.
+    python-oracledb Thick mode. It should be used with extreme caution. The
+    default value is 0.
 
 .. function:: Time(hour, minute, second)
 
@@ -1753,8 +1776,6 @@ module.html#session-pool-get-modes>`_ constants that were used in cx_Oracle
     of time (defined by the ``wait_timeout`` parameter) for a session to become
     available before returning with an error.
 
-    This constant is not supported in the python-oracledb Thin mode.
-
     .. note::
 
         This constant deprecates the ``SPOOL_ATTRVAL_TIMEDWAIT`` constant that

doc/src/api_manual/pool_params.rst

@@ -37,10 +37,10 @@ PoolParams Methods
     https_proxy=None, https_proxy_port=None, service_name=None, sid=None, \
     server_type=None, cclass=None, purity=None, expire_time=None, retry_count=None, \
     retry_delay=None, tcp_connect_timeout=None, ssl_server_dn_match=None, \
-    ssl_server_cert_dn=None, wallet_location=None, events=None, mode=None, \
-    disable_oob=None, stmtcachesize=None, edition=None, tag=None, matchanytag=None, \
-    config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], debug_jdwp=None, \
-    handle=None)
+    ssl_server_cert_dn=None, wallet_location=None, events=None, externalauth=None, \
+    mode=None, disable_oob=None, stmtcachesize=None, edition=None, tag=None, \
+    matchanytag=None, config_dir=None, appcontext=[], shardingkey=[], supershardingkey=[], \
+    debug_jdwp=None, handle=None)
 
   Sets one or more of the parameters.
 
@@ -58,14 +58,6 @@ PoolParams Attributes
 
   This attribute is supported in the python-oracledb Thin and Thick modes.
 
-.. attribute:: PoolParams.externalauth
-
-  This read-only attribute is a boolean that indicates whether the pool
-  uses external authentication to connect to the database. The default value
-  is False.
-
-  This attribute is only supported in the python-oracledb Thick mode.
-
 .. attribute:: PoolParams.getmode
 
   This read-write attribute is an integer that determines the behavior of

doc/src/conf.py

@@ -84,7 +84,10 @@
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
-html_style = 'default.css'
+# html_style = 'default.css'
+
+# The theme to use for readthedocs.
+html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,