10.0.x: Fix all Sphinx doc generation warnings (#11419)

doc/CMakeLists.txt

@@ -85,7 +85,7 @@ add_custom_command(
 add_custom_target(
   generate_docs
   COMMAND ${RUNPIPENV} run python ${CMAKE_CURRENT_SOURCE_DIR}/checkvers.py --check-version
-  COMMAND ${RUNPIPENV} run python -m sphinx -c ${CMAKE_CURRENT_BINARY_DIR} -b html ${CMAKE_CURRENT_SOURCE_DIR}
+  COMMAND ${RUNPIPENV} run python -m sphinx -W -c ${CMAKE_CURRENT_BINARY_DIR} -b html ${CMAKE_CURRENT_SOURCE_DIR}
           ${CMAKE_CURRENT_BINARY_DIR}/docbuild/html
   DEPENDS generate_docs_setup generate_svg_from_uml Pipfile.lock
   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}

doc/admin-guide/configuration/cache-basics.en.rst

@@ -16,6 +16,7 @@
    under the License.
 
 .. include:: ../../common.defs
+.. default-domain:: cpp
 
 .. _http-proxy-caching:
 
@@ -663,21 +664,21 @@ The buffer size calculations include all elements in the transaction, including
 any buffers associated with :ref:`transform plugins <developer-plugins-http-transformations>`.
 
 Transaction buffering control can be enabled globally by using configuration
-variables or by :c:func:`TSHttpTxnConfigIntSet` in a plugin.
+variables or by :func:`TSHttpTxnConfigIntSet` in a plugin.
 
 ================= ================================================== =======================================================
-Value             Variable                                           :c:func:`TSHttpTxnConfigIntSet` key
+Value             Variable                                           :func:`TSHttpTxnConfigIntSet` key
 ================= ================================================== =======================================================
-Enable buffering  :ts:cv:`proxy.config.http.flow_control.enabled`    :c:member:`TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED`
-Set high water    :ts:cv:`proxy.config.http.flow_control.high_water` :c:member:`TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER_MARK`
-Set low water     :ts:cv:`proxy.config.http.flow_control.low_water`  :c:member:`TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER_MARK`
+Enable buffering  :ts:cv:`proxy.config.http.flow_control.enabled`    :cpp:enumerator:`TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED`
+Set high water    :ts:cv:`proxy.config.http.flow_control.high_water` :cpp:enumerator:`TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER_MARK`
+Set low water     :ts:cv:`proxy.config.http.flow_control.low_water`  :cpp:enumerator:`TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER_MARK`
 ================= ================================================== =======================================================
 
 Be careful to always have the low water mark equal or less than the high water
 mark. If you set only one, the other will be set to the same value.
 
-If using :c:func:`TSHttpTxnConfigIntSet`, it must be called no later than
-:c:data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`.
+If using :func:`TSHttpTxnConfigIntSet`, it must be called no later than
+:cpp:enumerator:`TS_HTTP_READ_RESPONSE_HDR_HOOK`.
 
 .. _admin-configuration-reducing-origin-requests:
 

doc/admin-guide/files/plugin.config.en.rst

@@ -16,6 +16,7 @@
    under the License.
 
 .. include:: ../../common.defs
+.. default-domain:: cpp
 
 plugin.config
 *************
@@ -46,7 +47,7 @@ arbitrary effects on caching and authorization policies.
 
 An option list of whitespace-separated arguments may follow the plugin name.
 These are passed as an argument vector to the plugin's initialization function,
-:c:func:`TSPluginInit`. Arguments that begin with the ``$`` character designate
+:func:`TSPluginInit`. Arguments that begin with the ``$`` character designate
 |TS| configuration variables. These arguments will be replaced with the value
 of the corresponding configuration variable before the plugin is loaded.  When
 using configuration variable expansion, note that most |TS| configuration can

doc/admin-guide/files/records.yaml.en.rst

@@ -1345,7 +1345,7 @@ allow-plain
    to the error logging destination. Disabling this option prevents error
    responses (such as ``403``\ s) from appearing in the error logs. Any HTTP
    response status codes equal to, or higher, than the minimum code defined by
-   :c:data:`TS_HTTP_STATUS_BAD_REQUEST` are affected by this setting.
+   :cpp:enumerator:`TS_HTTP_STATUS_BAD_REQUEST` are affected by this setting.
 
 Parent Proxy Configuration
 ==========================
@@ -2216,7 +2216,7 @@ Cache Control
    configured.
 
    Note that plugins, particularly authorization plugins, which use the
-   :c:data:`TS_HTTP_OS_DNS_HOOK` hook may require this configuration variable
+   :cpp:enumerator:`TS_HTTP_OS_DNS_HOOK` hook may require this configuration variable
    to be disabled (``0``) in order to function properly. This will ensure that
    the hook will be evaluated and plugin execution will occur even when there
    is a fresh copy of the requested object in the cache (which would normally
@@ -2225,7 +2225,7 @@ Cache Control
    The downside is that the performance gain by skipping otherwise unnecessary
    DNS lookups is lost. Because the variable is overridable, you may retain
    this performance benefit for portions of your cache which do not require the
-   use of :c:data:`TS_HTTP_OS_DNS_HOOK` plugins, by ensuring that the setting
+   use of :cpp:enumerator:`TS_HTTP_OS_DNS_HOOK` plugins, by ensuring that the setting
    is first disabled within only the relevant transactions. Refer to the
    documentation on :ref:`admin-plugins-conf-remap` for more information.
 
@@ -3274,7 +3274,7 @@ Logging Configuration
 
    If set to a non-zero value :arg:`N` then any connection that takes longer than :arg:`N` milliseconds from accept to
    completion will cause its timing stats to be written to the :ts:cv:`debugging log file
-   <proxy.config.output.logfile>`. This is identifying data about the transaction and all of the :c:type:`transaction milestones <TSMilestonesType>`.
+   <proxy.config.output.logfile>`. This is identifying data about the transaction and all of the :cpp:type:`transaction milestones <TSMilestonesType>`.
 
 .. ts:cv:: CONFIG proxy.config.http2.connection.slow.log.threshold INT 0
    :reloadable:
@@ -3284,7 +3284,7 @@ Logging Configuration
    that takes longer than :arg:`N` milliseconds from open to close will cause
    its timing stats to be written to the :ts:cv:`debugging log file
    <proxy.config.output.logfile>`. This is identifying data about the
-   transaction and all of the :c:type:`transaction milestones <TSMilestonesType>`.
+   transaction and all of the :cpp:type:`transaction milestones <TSMilestonesType>`.
 
 .. ts:cv:: CONFIG proxy.config.http2.stream.slow.log.threshold INT 0
    :reloadable:
@@ -3294,7 +3294,7 @@ Logging Configuration
    that takes longer than :arg:`N` milliseconds from open to close will cause
    its timing stats to be written to the :ts:cv:`debugging log file
    <proxy.config.output.logfile>`. This is identifying data about the
-   transaction and all of the :c:type:`transaction milestones <TSMilestonesType>`.
+   transaction and all of the :cpp:type:`transaction milestones <TSMilestonesType>`.
 
 .. ts:cv:: CONFIG proxy.config.log.config.filename STRING logging.yaml
    :reloadable:

doc/admin-guide/files/strategies.yaml.en.rst

@@ -196,9 +196,9 @@ Each **strategy** in the list may using the following parameters:
   not have a value (e.g. not set by an API), we default back to the reqeust URL. Use one of:
 
    #. **request**: (**default**) Use the client request URL.
-   #. **cache**: Use the cache key URL as set via the APIs :c:func:`TSHttpTxnCacheLookupUrlSet()`
-      or :c:func:`TSCacheUrlSet()`. This would likely be set using a plugin such as **cachekey**.
-   #. **parent**: Use the parent URL as set via the API :c:func:`TSHttpTxnParentSelectionUrlSet`.
+   #. **cache**: Use the cache key URL as set via the APIs :cpp:func:`TSHttpTxnCacheLookupUrlSet()`
+      or :cpp:func:`TSCacheUrlSet()`. This would likely be set using a plugin such as **cachekey**.
+   #. **parent**: Use the parent URL as set via the API :cpp:func:`TSHttpTxnParentSelectionUrlSet`.
       This again is likely set via an existing plugin such as the **cachekey** plugin.
 
 - **go_direct**: A boolean value indicating whether a transaction may bypass proxies and go direct to the origin. Defaults to **true**

doc/admin-guide/layer-4-routing.en.rst

@@ -16,7 +16,7 @@
    under the License.
 
 .. include:: ../common.defs
-.. default-domain:: c
+.. default-domain:: cpp
 .. _layer-4-routing:
 
 Layer 4 Routing
@@ -123,10 +123,10 @@ The sequence of network activity for a Client connecting to ``service-2`` is
 
 Note the destination for the outbound TCP connection and the HTTP ``CONNECT`` is the same. If this
 is a problem (which it will be in general) a plugin is needed to change the URL in the ``CONNECT``.
-In this case the proxy request is available in the :c:macro:`TS_HTTP_TXN_START_HOOK` hook. This
+In this case the proxy request is available in the :enumerator:`TS_HTTP_TXN_START_HOOK` hook. This
 cannot be done using remap because for a ``CONNECT`` there is no remap phase. Note that for a
 tunneled connection like this, the only transaction hooks that will be triggered are
-:c:macro:`TS_HTTP_TXN_START_HOOK` and :c:macro:`TS_HTTP_TXN_CLOSE_HOOK`. In addition, because |TS|
+:enumerator:`TS_HTTP_TXN_START_HOOK` and :enumerator:`TS_HTTP_TXN_CLOSE_HOOK`. In addition, because |TS|
 does not terminate (and therefore does not decrypt) the connection, it cannot be cached or served from
 cache.
 

doc/admin-guide/logging/formatting.en.rst

@@ -16,6 +16,7 @@
    under the License.
 
 .. include:: ../../common.defs
+.. default-domain:: cpp
 
 .. _admin-logging-formats:
 
@@ -545,12 +546,12 @@ Field Source           Description
 ===== ================ ============================================================
 piid  Proxy Plugin     Plugin ID for the current transaction. This is set for
                        plugin driven transactions via
-                       :c:func:`TSHttpConnectWithPluginId`. or
-                       :c:func:`TSHttpConnectPlugin`.
+                       :func:`TSHttpConnectWithPluginId`. or
+                       :func:`TSHttpConnectPlugin`.
 pitag Proxy Plugin     Plugin tag for the current transaction. This is set for
                        plugin driven transactions via
-                       :c:func:`TSHttpConnectWithPluginId`. or
-                       :c:func:`TSHttpConnectPlugin`.
+                       :func:`TSHttpConnectWithPluginId`. or
+                       :func:`TSHttpConnectPlugin`.
 cqint Client Request   If a request was generated internally (via a plugin), then
                        this has a value of ``1``, otherwise ``0``. This can be
                        useful when tracking internal only requests, such as those
@@ -797,7 +798,7 @@ tts   Client Request          Same as ttms_, but in integer seconds (no
         %<{Milestone field name1-Milestone field name2}msdms>
 
     For more information on transaction milestones in |TS|, refer to the
-    documentation on :c:func:`TSHttpTxnMilestoneGet`.
+    documentation on :func:`TSHttpTxnMilestoneGet`.
 
 .. _admin-logging-fields-urls:
 

doc/admin-guide/monitoring/statistics/core/eventloop.en.rst

@@ -12,7 +12,7 @@
    under the License.
 
 .. include:: ../../../../common.defs
-
+.. default-domain:: cpp
 .. _admin-stats-core-eventloop:
 
 Event Loop
@@ -199,6 +199,6 @@ high then it is likely transactions are experiencing significant latency.
 .. ts:stat:: global proxy.process.api.time.*ms integer
 
    A set of statistics that provide a histogram of total time spent in plugins. This is sampled
-   per plugin, rather than the aggregate value for milestone :c:macro:`TS_MILESTONE_PLUGIN_TOTAL`.
+   per plugin, rather than the aggregate value for milestone :enumerator:`TS_MILESTONE_PLUGIN_TOTAL`.
 
    See :ts:stat:`proxy.process.eventloop.time.*ms` for technical details.

doc/admin-guide/plugins/background_fetch.en.rst

@@ -13,6 +13,7 @@
 
 .. _admin-plugins-background-fetch:
 .. include:: /common.defs
+.. default-domain:: cpp
 
 Background Fetch Plugin
 ***********************
@@ -50,7 +51,7 @@ Examining the responses from origin, we decide to trigger a background fetch of
 *  The response is a ``206`` response
 
 *  The original client request, and the Origin server response, is clearly indicating that the
-   response is cacheable. This uses the new API :c:func:`TSHttpTxnIsCacheable()`, which also implies
+   response is cacheable. This uses the new API :func:`TSHttpTxnIsCacheable()`, which also implies
    honoring current Traffic Server configurations.
 
 

doc/admin-guide/plugins/header_rewrite.en.rst

@@ -12,6 +12,7 @@
    under the License.
 
 .. include:: ../../common.defs
+.. default-domain:: cpp
 .. highlight:: none
 
 .. _admin-plugins-header-rewrite:
@@ -449,7 +450,7 @@ INTERNAL-TRANSACTION
     cond %{INTERNAL-TRANSACTION}
 
 Returns true if the current transaction was internally-generated by |TS| (using
-:c:func:`TSHttpTxnIsInternal`). These transactions are not initiated by
+:func:`TSHttpTxnIsInternal`). These transactions are not initiated by
 external client requests, but are triggered (often by plugins) entirely within
 the |TS| process.
 
@@ -563,7 +564,7 @@ TCP-INFO
     cond %{<name>}
         add-header @PropertyName "%{TCP-INFO}"
 
-This operation records TCP Info struct field values as an Internal remap as well as global header at the event hook specified by the condition. Supported hook conditions include TXN_START_HOOK, SEND_RESPONSE_HEADER_HOOK and TXN_CLOSE_HOOK in the Global plugin and REMAP_PSEUDO_HOOK, SEND_RESPONSE_HEADER_HOOK and TXN_CLOSE_HOOK in the Remap plugin. Conditions supported as request headers include TXN_START_HOOK and REMAP_PSEUDO_HOOK. The other conditions are supported as response headers. TCP Info fields currently recorded include rtt, rto, snd_cwnd and all_retrans. This operation is not supported on transactions originated within Traffic Server (for e.g using the |TS| :c:func:`TSHttpTxnIsInternal`)
+This operation records TCP Info struct field values as an Internal remap as well as global header at the event hook specified by the condition. Supported hook conditions include TXN_START_HOOK, SEND_RESPONSE_HEADER_HOOK and TXN_CLOSE_HOOK in the Global plugin and REMAP_PSEUDO_HOOK, SEND_RESPONSE_HEADER_HOOK and TXN_CLOSE_HOOK in the Remap plugin. Conditions supported as request headers include TXN_START_HOOK and REMAP_PSEUDO_HOOK. The other conditions are supported as response headers. TCP Info fields currently recorded include rtt, rto, snd_cwnd and all_retrans. This operation is not supported on transactions originated within Traffic Server (for e.g using the |TS| :func:`TSHttpTxnIsInternal`)
 
 Condition Operands
 ------------------
@@ -742,7 +743,7 @@ set-debug
   set-debug
 
 When invoked, this operator enables the internal transaction debugging flag
-(via :c:func:`TSHttpTxnDebugSet`), which causes debug messages to be printed to
+(via :func:`TSHttpTxnDebugSet`), which causes debug messages to be printed to
 the appropriate logs even when the debug tag has not been enabled. For
 additional information on |TS| debugging statements, refer to
 :ref:`developer-debug-tags` in the developer's documentation.

doc/admin-guide/plugins/lua.en.rst

@@ -16,6 +16,7 @@
    under the License.
 
 .. include:: ../../common.defs
+.. default-domain:: cpp
 
 .. _admin-plugins-ts-lua:
 
@@ -924,7 +925,7 @@ ts.client_request.get_url
 
 **context:** do_remap/do_os_response or do_global_* or later
 
-**description:** This function can be used to retrieve the client request url (:c:func:`TSHttpTxnEffectiveUrlStringGet`).
+**description:** This function can be used to retrieve the client request url (:func:`TSHttpTxnEffectiveUrlStringGet`).
 
 Here is an example:
 

doc/admin-guide/plugins/multiplexer.en.rst

@@ -38,7 +38,7 @@ Description
    #. Copies the resulting request (POST bodies are copied via the :ref:`HTTP Transform <developer-plugins-http-transformations>` mechanism).
    #. Changes the ``Host`` header of the copy according to ``pparam`` from the remap rule.
    #. Changes ``X-Multiplexer`` header value to ``copy`` instead of ``original``.
-   #. Asynchronously sends the copied request with :c:func:`TSHttpConnect`.
+   #. Asynchronously sends the copied request with :func:`TSHttpConnect`.
    #. The copied request with the specified host is then itself processed via :file:`remap.config`.
 
 |Name| dispatches the requests in the background without blocking the original request. Multiplexed

doc/admin-guide/plugins/regex_revalidate.en.rst

@@ -141,7 +141,7 @@ Matches Only Post-Remapping
 The regular expressions in revalidation rules see only the final, remapped URL
 in a transaction. As such, they cannot be used to distinguish between two
 client-facing URLs which are mapped to the same origin object. This is due to
-the fact that the plugin uses :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK`.
+the fact that the plugin uses :cpp:enumerator:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK`.
 
 Removing Rules
 --------------

doc/admin-guide/plugins/txn_box/txnbox_common.defs

@@ -11,7 +11,7 @@
    or implied.  See the License for the specific language governing permissions and limitations
    under the License.
 
-.. default-domain:: c
+.. default-domain:: cpp
 
 .. |TxB| replace:: TxnBox
 .. |libswoc| replace:: LibSWOC++

doc/admin-guide/plugins/txn_box/user/DirectiveReference.en.rst

@@ -438,7 +438,7 @@ Utility
    file is avaiable during a subsequent check and is updated (newer than the last load time) it will
    be loaded and used instead of the text.
 
-   .. seealso:: :ref:`ex-text-block`, :ref:`mod-as-text-block`
+   .. seealso:: :ex:`text-block`.
 
 .. directive:: error
 

doc/admin-guide/plugins/xdebug.en.rst

@@ -17,6 +17,8 @@
 
 .. include:: ../../common.defs
 
+.. default-domain:: cpp
+
 .. _admin-plugins-xdebug:
 
 XDebug Plugin
@@ -115,7 +117,7 @@ X-Milestones
     The ``X-Milestones`` header contains detailed information about
     how long the transaction took to traverse portions of the HTTP
     state machine. The timing information is obtained from the
-    :c:func:`TSHttpTxnMilestoneGet` API. Each milestone value is a
+    :func:`TSHttpTxnMilestoneGet` API. Each milestone value is a
     fractional number of seconds since the beginning of the
     transaction.
 

doc/conf.cmake.in.py

@@ -178,14 +178,30 @@ def setup(app):
 
 nitpicky = True
 nitpick_ignore = [
-    ('c:identifier', 'int64_t'),
-    ('c:identifier', 'uint64_t'),
-    ('c:identifier', 'uint8_t'),
-    ('c:identifier', 'int32_t'),
-    ('c:identifier', 'size_t'),
-    ('c:identifier', 'ssize_t'),
-    ('c:identifier', 'sockaddr'),
-    ('c:identifier', 'time_t'),
+    ('cpp:identifier', 'int64_t'),
+    ('cpp:identifier', 'uint64_t'),
+    ('cpp:identifier', 'uint8_t'),
+    ('cpp:identifier', 'int32_t'),
+    ('cpp:identifier', 'size_t'),
+    ('cpp:identifier', 'ssize_t'),
+    ('cpp:identifier', 'sockaddr'),
+    ('cpp:identifier', 'time_t'),
+    ('cpp:identifier', 'time_t'),
+    ('cpp:identifier', 'swoc'),
+    ('cpp:identifier', 'swoc::Rv<Directive::Handle>'),
+    ('cpp:identifier', 'Directive::Handle'),
+    ('cpp:identifier', 'CfgStaticData'),
+    ('cpp:identifier', 'YAML'),
+    ('cpp:identifier', 'YAML::Node'),
+    ('cpp:identifier', 'swoc'),
+    ('cpp:identifier', 'swoc::TextView'),
+    ('cpp:identifier', 'swoc'),
+    ('cpp:identifier', 'swoc::TextView'),
+    ('cpp:identifier', 'YAML'),
+    ('cpp:identifier', 'YAML::Node'),
+    ('cpp:identifier', 'swoc'),
+    ('cpp:identifier', 'swoc::Errata'),
+    ('cpp:identifier', 'CfgStaticData'),
     ('cpp:identifier', 'T'),  # template arg
     ('cpp:identifier', 'F'),  # template arg
     ('cpp:identifier', 'Args'),  # variadic template arg

doc/conf.py

@@ -182,14 +182,14 @@ def setup(app):
 
 nitpicky = True
 nitpick_ignore = [
-    ('c:identifier', 'int64_t'),
-    ('c:identifier', 'uint64_t'),
-    ('c:identifier', 'uint8_t'),
-    ('c:identifier', 'int32_t'),
-    ('c:identifier', 'size_t'),
-    ('c:identifier', 'ssize_t'),
-    ('c:identifier', 'sockaddr'),
-    ('c:identifier', 'time_t'),
+    ('cpp:identifier', 'int64_t'),
+    ('cpp:identifier', 'uint64_t'),
+    ('cpp:identifier', 'uint8_t'),
+    ('cpp:identifier', 'int32_t'),
+    ('cpp:identifier', 'size_t'),
+    ('cpp:identifier', 'ssize_t'),
+    ('cpp:identifier', 'sockaddr'),
+    ('cpp:identifier', 'time_t'),
     ('cpp:identifier', 'T'),  # template arg
     ('cpp:identifier', 'F'),  # template arg
     ('cpp:identifier', 'Args'),  # variadic template arg