Doc: Update documentation to build cleanly in Sphinx 3

doc/admin-guide/logging/cache-results.en.rst

@@ -105,7 +105,7 @@ the object to the client.
 .. _crc-tcp-cf-hit:
 
 TCP_CF_HIT
--------
+----------
 
 A valid copy of the requested object is being updated in the cache and Traffic Server sent
 the object to the client.

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

@@ -32,7 +32,7 @@ Cookie Based Routing Inside TrafficServer Using cookie_remap
 
     * `Comments <#comments>`_
     * `cookie: X|X.Y <#cookie-xxy>`_
-    * `target: purl <#purl>`_
+    * `target: puri <#purl>`_
     * `operation: exists|not exists|string|regex|bucket <#operation-existsnot-existsstringregexbucket>`_
     * `match: str <#match-str>`_
     * `regex: str <#regex-str>`_
@@ -126,15 +126,15 @@ cookie: X|X.Y
 This sub-operation is testing against the X cookie or X.Y cookie where X.Y denotes the X cookie, sub cookie Y
 e.g
 
+.. code-block:: text
 
-.. raw:: html
-
-   <pre>
    A=ACOOKIE;B=data&f=fsub&z=zsub;
-   A will operate on ACOOKIE
-   B will operate on data&f=fsub&z=zsub
-   B.f will operate on fsub
-   </pre>
+
+A will operate on ``ACOOKIE``
+
+B will operate on ``data&f=fsub&z=zsub``
+
+B.f will operate on ``fsub``
 
 target: puri
 ^^^^^^^^^^^^

doc/conf.py

@@ -65,10 +65,9 @@
 with open(LOCAL_CONFIG) as f:
     exec(compile(f.read(), LOCAL_CONFIG, 'exec'))
 
-if version_info >= (1, 4):
-    extensions.append('sphinx.ext.imgmath')
-else:
-    extensions.append('sphinx.ext.pngmath')
+if version_info < (3, 0):
+    print("Documentation requires Sphinx 3.0 or later.")
+    exit(1)
 
 # XXX Disabling docxygen for now, since it make RTD documentation builds time
 # out, eg. https://readthedocs.org/projects/trafficserver/builds/3525976/
@@ -172,16 +171,18 @@
 #modindex_common_prefix = []
 
 nitpicky = True
-nitpick_ignore = [('c:type', 'int64_t'),
-                  ('c:type', 'bool'),
-                  ('c:type', 'sockaddr'),
+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', 'T'),  # template arg
                   ('cpp:identifier', 'F'),  # template arg
                   ('cpp:identifier', 'Args'),  # variadic template arg
                   ('cpp:identifier', 'Rest'),  # variadic template arg
-                  ('c:type', 'uint64_t'),
-                  ('c:type', 'uint8_t'),
-                  ('c:type', 'int32_t')
                   ]
 
 # Autolink issue references.

doc/developer-guide/api/functions/TSDebug.en.rst

@@ -26,7 +26,7 @@ Traffic Server Debugging APIs.
 Synopsis
 ========
 
-.. code-block:: cpp
+.. code-block:: c
 
     #include <ts/ts.h>
 
@@ -47,8 +47,8 @@ Synopsis
 .. function:: const char* TSHttpServerStateNameLookup(TSServerState state)
 .. function:: const char* TSHttpHookNameLookup(TSHttpHookID hook)
 .. function:: const char* TSHttpEventNameLookup(TSEvent event)
-.. macro:: void TSAssert( ... )
-.. macro:: void TSReleaseAssert( ... )
+.. macro:: TSAssert( ... )
+.. macro:: TSReleaseAssert( ... )
 
 diags.log
 =========

doc/developer-guide/api/functions/TSHttpConnectWithPluginId.en.rst

@@ -45,7 +45,7 @@ stack via the loopback interface.
 
 :arg:`addr`
    This is the network address of the target of the connection.
-   This includes the port which should be stored in the :c:type:`sockaddr`
+   This includes the port which should be stored in the :code:`sockaddr`
    structure pointed at by :arg:`addr`.
 
 :arg:`tag`

doc/developer-guide/api/functions/TSHttpSsnIdGet.en.rst

@@ -38,7 +38,7 @@ Description
 Return Values
 =============
 
-Returns a :type:`int64_t` as the unique ID
+Returns a :code:`int64_t` as the unique ID
 
 See also
 ========

doc/developer-guide/api/functions/TSHttpTxnInfoIntGet.en.rst

@@ -37,34 +37,34 @@ requested info. For example, cache related info may be available only at or afte
 
 The :c:type:`TSHttpTxnInfoKey` currently supports the below integer-based info about a transaction
 
-.. c:type:: TSHttpTxnInfoKey
+.. c:enum:: TSHttpTxnInfoKey
 
-   .. c:member:: TS_TXN_INFO_CACHE_HIT_RAM
+   .. c:enumerator:: TS_TXN_INFO_CACHE_HIT_RAM
 
-      This info is available at or after :c:member:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of :literal:`1` indicates that the response
+      This info is available at or after :c:macro:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of :literal:`1` indicates that the response
       is returned from RAM cache. A value of :literal:`0` indicates otherwise.
 
-   .. c:member:: TS_TXN_INFO_CACHE_COMPRESSED_IN_RAM
+   .. c:enumerator:: TS_TXN_INFO_CACHE_COMPRESSED_IN_RAM
 
-      This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
+      This info is available at or after :c:macro:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
       is returned from RAM cache and is compressed. A value of 0 indicates otherwise.
 
-   .. c:member:: TS_TXN_INFO_CACHE_HIT_RWW
+   .. c:enumerator:: TS_TXN_INFO_CACHE_HIT_RWW
 
       This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
       is returned via Read-While-Writer functionality. A value of 0 indicates otherwise.
 
-   .. c:member:: TS_TXN_INFO_CACHE_OPEN_READ_TRIES
+   .. c:enumerator:: TS_TXN_INFO_CACHE_OPEN_READ_TRIES
 
       This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the number of cache open
       read reattempts made by the transaction on cache open read failure.
 
-   .. c:member:: TS_TXN_INFO_CACHE_OPEN_WRITE_TRIES
+   .. c:enumerator:: TS_TXN_INFO_CACHE_OPEN_WRITE_TRIES
 
       This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the number of cache open
       write reattempts made by the transaction on cache open write failure.
 
-   .. c:member:: TS_TXN_INFO_CACHE_VOLUME
+   .. c:enumerator:: TS_TXN_INFO_CACHE_VOLUME
 
       This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the cache volume ID used
       for the cache object associated with the transaction.

doc/developer-guide/api/functions/TSHttpTxnIsInternal.en.rst

@@ -24,7 +24,7 @@ Test whether a request is internally-generated.
 Synopsis
 ========
 
-.. code-block:: cpp
+.. code-block:: c
 
     #include <ts/ts.h>
 
@@ -43,7 +43,7 @@ was originated within Traffic Server.
 Return Values
 =============
 
-Both these APIs return a :type:`int`, indicating whether the
+Both these APIs return a :code:`int`, indicating whether the
 request was internal (:literal:`1`) or not (:literal:`0`).
 
 Examples

doc/developer-guide/api/functions/TSHttpTxnMilestoneGet.en.rst

@@ -42,105 +42,105 @@ lifetime of a transaction and are measured in nanoseconds from the beginning of
 the transaction. :arg:`time` is used a pointer to storage to update if the call
 is successful.
 
-.. type:: TSMilestonesType
+.. enum:: TSMilestonesType
 
-	An enumeration of the valid indices of transaction milestone data.
+   An enumeration of the valid indices of transaction milestone data.
 
-	.. macro:: TS_MILESTONE_SM_START
+   .. enumerator:: TS_MILESTONE_SM_START
 
-		Transaction state machine is initialized.
+      Transaction state machine is initialized.
 
-	.. macro:: TS_MILESTONE_UA_BEGIN
+   .. enumerator:: TS_MILESTONE_UA_BEGIN
 
-		The client connection is accepted.
+      The client connection is accepted.
 
-	.. macro:: TS_MILESTONE_UA_READ_HEADER_DONE
+   .. enumerator:: TS_MILESTONE_UA_READ_HEADER_DONE
 
-		The request header from the client has been read and parsed.
+      The request header from the client has been read and parsed.
 
-	.. macro:: TS_MILESTONE_CACHE_OPEN_READ_BEGIN
+   .. enumerator:: TS_MILESTONE_CACHE_OPEN_READ_BEGIN
 
-		Initiate read of the cache.
+      Initiate read of the cache.
 
-	.. macro:: TS_MILESTONE_CACHE_OPEN_READ_END
+   .. enumerator:: TS_MILESTONE_CACHE_OPEN_READ_END
 
-		Initial cache read has resolved.
+      Initial cache read has resolved.
 
-	.. macro:: TS_MILESTONE_CACHE_OPEN_WRITE_BEGIN
+   .. enumerator:: TS_MILESTONE_CACHE_OPEN_WRITE_BEGIN
 
-		Start open for cache write.
+      Start open for cache write.
 
-	.. macro:: TS_MILESTONE_CACHE_OPEN_WRITE_END
+   .. enumerator:: TS_MILESTONE_CACHE_OPEN_WRITE_END
 
-		Cache has been opened for write.
+      Cache has been opened for write.
 
-	.. macro:: TS_MILESTONE_DNS_LOOKUP_BEGIN
+   .. enumerator:: TS_MILESTONE_DNS_LOOKUP_BEGIN
 
-		Initiate host resolution in HostDB
+      Initiate host resolution in HostDB
 
-	.. macro:: TS_MILESTONE_DNS_LOOKUP_END
+   .. enumerator:: TS_MILESTONE_DNS_LOOKUP_END
 
-		Host resolution resolves.
+      Host resolution resolves.
 
-	.. macro:: TS_MILESTONE_SERVER_FIRST_CONNECT
+   .. enumerator:: TS_MILESTONE_SERVER_FIRST_CONNECT
 
-		First time origin server connect attempted or shared session attached.
+      First time origin server connect attempted or shared session attached.
 
-	.. macro:: TS_MILESTONE_SERVER_CONNECT
+   .. enumerator:: TS_MILESTONE_SERVER_CONNECT
 
-		Most recent time origin server connect attempted or shared session attached.
+      Most recent time origin server connect attempted or shared session attached.
 
-	.. macro:: TS_MILESTONE_SERVER_CONNECT_END
+   .. enumerator:: TS_MILESTONE_SERVER_CONNECT_END
 
-		More recent time a connection attempt was resolved.
+      More recent time a connection attempt was resolved.
 
-	.. macro:: TS_MILESTONE_SERVER_BEGIN_WRITE
+   .. enumerator:: TS_MILESTONE_SERVER_BEGIN_WRITE
 
-		First byte is written to the origin server connection.
+      First byte is written to the origin server connection.
 
-	.. macro:: TS_MILESTONE_SERVER_FIRST_READ
+   .. enumerator:: TS_MILESTONE_SERVER_FIRST_READ
 
-		First byte is read from connection to origin server.
+      First byte is read from connection to origin server.
 
-	.. macro:: TS_MILESTONE_SERVER_READ_HEADER_DONE
+   .. enumerator:: TS_MILESTONE_SERVER_READ_HEADER_DONE
 
-		Origin server response has been read and parsed.
+      Origin server response has been read and parsed.
 
-	.. macro:: TS_MILESTONE_UA_BEGIN_WRITE
+   .. enumerator:: TS_MILESTONE_UA_BEGIN_WRITE
 
-		The response header write to the client starts.
+      The response header write to the client starts.
 
-	.. macro:: TS_MILESTONE_SERVER_CLOSE
+   .. enumerator:: TS_MILESTONE_SERVER_CLOSE
 
-		Last I/O activity on origin server connection.
+      Last I/O activity on origin server connection.
 
-	.. macro:: TS_MILESTONE_UA_CLOSE
+   .. enumerator:: TS_MILESTONE_UA_CLOSE
 
-		Last I/O activity on the client socket, or connection abort.
+      Last I/O activity on the client socket, or connection abort.
 
-	.. macro:: TS_MILESTONE_SM_FINISH
+   .. enumerator:: TS_MILESTONE_SM_FINISH
 
-		Transaction has finished, state machine final logging has started.
+      Transaction has finished, state machine final logging has started.
 
-	.. macro:: TS_MILESTONE_PLUGIN_ACTIVE
+   .. enumerator:: TS_MILESTONE_PLUGIN_ACTIVE
 
-		Amount of time plugins were active (running plugin code).
+      Amount of time plugins were active (running plugin code).
 
-	.. macro:: TS_MILESTONE_PLUGIN_TOTAL
+   .. enumerator:: TS_MILESTONE_PLUGIN_TOTAL
 
-		Amount of time spent in or waiting for plugins.
+      Amount of time spent in or waiting for plugins.
 
-   .. macro:: TS_MILESTONE_TLS_HANDSHAKE_START
+   .. enumerator:: TS_MILESTONE_TLS_HANDSHAKE_START
 
       Timestamp when the server starts the TLS handshake. 0 if no handshake is performed (connection reuse).
 
-   .. macro:: TS_MILESTONE_TLS_HANDSHAKE_END
+   .. enumerator:: TS_MILESTONE_TLS_HANDSHAKE_END
 
       Timestamp when the server completes the TLS handshake. 0 if no handshake is performed (connection reuse).
 
-	.. macro:: TS_MILESTONE_LAST_ENTRY
+   .. enumerator:: TS_MILESTONE_LAST_ENTRY
 
-		A pseudo index which is set to be one more than the last valid index. This is useful for looping over the data.
+      A pseudo index which is set to be one more than the last valid index. This is useful for looping over the data.
 
 
 *  The server connect times predate the transmission of the :literal:`SYN`

doc/developer-guide/api/functions/TSLifecycleHookAdd.en.rst

@@ -26,7 +26,7 @@ TSLifecycleHookAdd
 Synopsis
 ========
 
-.. code-block:: cpp
+.. code-block:: c
 
     #include <ts/ts.h>
 
@@ -112,21 +112,21 @@ Types
 
       Invoked with the event :c:data:`TS_EVENT_LIFECYCLE_SHUTDOWN` and ``NULL`` data.
 
-.. c:type:: TSPluginMsg
+.. c:struct:: TSPluginMsg
 
-   The format of the data for the plugin message event :c:data:`TS_EVENT_LIFECYCLE_MSG`.
+   The data for the plugin message event :c:data:`TS_EVENT_LIFECYCLE_MSG`.
 
-.. c:member:: const char * TSPluginMsg::tag
+   .. c:var:: const char * tag
 
-   The tag of the message. This is a null terminated string.
+      The tag of the message. This is a null terminated string.
 
-.. c:member:: const void * TSPluginMsg::data
+   .. c:var:: const void * data
 
-   Message data (payload). This is a raw slab of bytes - no structure is guaranteed.
+      Message data (payload). This is a raw slab of bytes - no structure is guaranteed.
 
-.. c:member:: size_t TSPluginMsg::data_size
+   .. c:var:: size_t data_size
 
-   The size of :member:`TSPluginMsg::data`.
+      The number of valid bytes pointed at by :var:`TSPluginMsg.data`.
 
 Ordering
 ========