Documentation improvements.

Author: anthony-tuininga

doc/src/_ext/table_with_summary.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2022, Oracle and/or its affiliates.
+# Copyright (c) 2022, 2024, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -50,6 +50,22 @@ def run(self):
 
 
 class HTMLTranslator(sphinx.writers.html5.HTML5Translator):
+    def visit_paragraph(self, node):
+        children = node.children
+        if len(children) == 1 and children[0].astext() == "No relevant notes":
+            atts = {
+                "style": "clip: rect(1px, 1px, 1px, 1px);"
+                "clip-path: inset(50%);"
+                "height: 1px;"
+                "overflow: hidden;"
+                "position: absolute;"
+                "white-space: nowrap;"
+                "width: 1px;"
+            }
+            self.body.append(self.starttag(node, "p", "", **atts))
+        else:
+            super().visit_paragraph(node)
+
     def visit_table(self, node):
         if version.parse(sphinx.__version__) > version.parse("4.2.0"):
             self._table_row_indices = [0]

doc/src/user_guide/appendix_a.rst

@@ -358,111 +358,111 @@ values.
       - Supported Python Types
     * - VARCHAR2
       - :data:`~oracledb.DB_TYPE_VARCHAR`
-      -
+      - No relevant notes
       - bytes, str
     * - NVARCHAR2
       - :data:`~oracledb.DB_TYPE_NVARCHAR`
-      -
+      - No relevant notes
       - bytes, str
     * - NUMBER, FLOAT
       - :data:`~oracledb.DB_TYPE_NUMBER`
-      -
+      - No relevant notes
       - bool, int, float, decimal.Decimal
     * - DATE
       - :data:`~oracledb.DB_TYPE_DATE`
-      -
+      - No relevant notes
       - datetime.date, datetime.datetime
     * - BOOLEAN (PL/SQL and Oracle Database 23c SQL)
       - :data:`~oracledb.DB_TYPE_BOOLEAN`
-      -
+      - No relevant notes
       - Any type convertible to bool
     * - BINARY_DOUBLE
       - :data:`~oracledb.DB_TYPE_BINARY_DOUBLE`
-      -
+      - No relevant notes
       - bool, int, float, decimal.Decimal
     * - BINARY_FLOAT
       - :data:`~oracledb.DB_TYPE_BINARY_FLOAT`
-      -
+      - No relevant notes
       - bool, int, float, decimal.Decimal
     * - TIMESTAMP
       - :data:`~oracledb.DB_TYPE_TIMESTAMP`
-      -
+      - No relevant notes
       - datetime.date, datetime.datetime
     * - TIMESTAMP WITH TIME ZONE
       - :data:`~oracledb.DB_TYPE_TIMESTAMP_TZ`
-      -
+      - No relevant notes
       - datetime.date, datetime.datetime
     * - TIMESTAMP WITH LOCAL TIME ZONE
       - :data:`~oracledb.DB_TYPE_TIMESTAMP_LTZ`
-      -
+      - No relevant notes
       - datetime.date, datetime.datetime
     * - INTERVAL YEAR TO MONTH
       - :data:`~oracledb.DB_TYPE_INTERVAL_YM`
       - Not supported in python-oracledb.
       - Cannot be set
     * - INTERVAL DAY TO SECOND
       - :data:`~oracledb.DB_TYPE_INTERVAL_DS`
-      -
+      - No relevant notes
       - datetime.timedelta
     * - RAW
       - :data:`~oracledb.DB_TYPE_RAW`
-      -
+      - No relevant notes
       - bytes, str
     * - LONG
       - :data:`~oracledb.DB_TYPE_LONG`
-      -
+      - No relevant notes
       - bytes, str
     * - LONG RAW
       - :data:`~oracledb.DB_TYPE_LONG_RAW`
-      -
+      - No relevant notes
       - bytes, str
     * - ROWID
       - :data:`~oracledb.DB_TYPE_ROWID`
-      -
+      - No relevant notes
       - bytes, str
     * - UROWID
       - :data:`~oracledb.DB_TYPE_ROWID`, :data:`~oracledb.DB_TYPE_UROWID` (only supported in python-oracledb Thin mode)
       - May show :data:`~oracledb.DB_TYPE_UROWID` in metadata. See :ref:`Query Metadata Differences <querymetadatadiff>`.
       - bytes, str
     * - CHAR
       - :data:`~oracledb.DB_TYPE_CHAR`
-      -
+      - No relevant notes
       - bytes, str
     * - BLOB
       - :data:`~oracledb.DB_TYPE_BLOB`
-      -
+      - No relevant notes
       - :ref:`oracledb.LOB <lobobj>`, bytes, str
     * - CLOB
       - :data:`~oracledb.DB_TYPE_CLOB`
-      -
+      - No relevant notes
       - :ref:`oracledb.LOB <lobobj>`, bytes, str
     * - NCHAR
       - :data:`~oracledb.DB_TYPE_NCHAR`
-      -
+      - No relevant notes
       - bytes, str
     * - NCLOB
       - :data:`~oracledb.DB_TYPE_NCLOB`, :data:`~oracledb.DB_TYPE_LONG_NVARCHAR` (if fetching NCLOB as a string)
-      -
+      - No relevant notes
       - :ref:`oracledb.LOB <lobobj>`, bytes, str
     * - BFILE
       - :data:`~oracledb.DB_TYPE_BFILE`
       - Not supported in python-oracledb Thin mode.
       - Cannot be set
     * - JSON
       - :data:`~oracledb.DB_TYPE_JSON`
-      -
+      - No relevant notes
       - Any type convertible to Oracle JSON
     * - REF CURSOR (PL/SQL OR nested cursor)
       - :data:`~oracledb.DB_TYPE_CURSOR`
-      -
+      - No relevant notes
       - :ref:`oracledb.Cursor <cursorobj>`
     * - PLS_INTEGER
       - :data:`~oracledb.DB_TYPE_BINARY_INTEGER`
-      -
+      - No relevant notes
       - bool, int, float, decimal.Decimal
     * - BINARY_INTEGER
       - :data:`~oracledb.DB_TYPE_BINARY_INTEGER`
-      -
+      - No relevant notes
       - bool, int, float, decimal.Decimal
     * - REF
       - n/a
@@ -474,7 +474,7 @@ values.
       - bytes, str
     * - User-defined types (object type, VARRAY, records, collections, SDO_*types)
       - :data:`~oracledb.DB_TYPE_OBJECT`
-      -
+      - No relevant notes
       - OBJECT of specific type
 
 Binding of contiguous PL/SQL Index-by BINARY_INTEGER arrays of string, number, and date are

doc/src/user_guide/appendix_b.rst

@@ -109,43 +109,43 @@ used in :meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`,
       - Used in Easy Connect Strings. It is same as ``MY_WALLET_DIRECTORY`` in a connect descriptor.
     * - MY_WALLET_DIRECTORY
       - wallet_location
-      -
+      - No relevant notes
     * - EXPIRE_TIME
       - expire_time
-      -
+      - No relevant notes
     * - HTTPS_PROXY
       - https_proxy
-      -
+      - No relevant notes
     * - HTTPS_PROXY_PORT
       - https_proxy_port
-      -
+      - No relevant notes
     * - RETRY_COUNT
       - retry_count
-      -
+      - No relevant notes
     * - RETRY_DELAY
       - retry_delay
-      -
+      - No relevant notes
     * - TRANSPORT_CONNECT_TIMEOUT
       - tcp_connect_timeout
-      -
+      - No relevant notes
     * - POOL_CONNECTION_CLASS
       - cclass
-      -
+      - No relevant notes
     * - POOL_PURITY
       - purity
-      -
+      - No relevant notes
     * - SERVICE_NAME
       - service_name
-      -
+      - No relevant notes
     * - SID
       - sid
-      -
+      - No relevant notes
     * - PORT
       - port
-      -
+      - No relevant notes
     * - PROTOCOL
       - protocol
-      -
+      - No relevant notes
 
 In python-oracledb Thin mode, using the ``POOL_CONNECTION_CLASS`` or
 ``POOL_PURITY`` parameters in a connection string is similar to setting the