Documentation cleanup (#7798)

* Fix indentation and alignment errors tabs used for alignment, spaces used as indentation, etc. * trim trailing whitespace * Add missing admonitions for timestamp format changes * Fix formatting Mostly this means the spacing and alignment in field lists, but also some of the fields got out of lexical order as well, and I ensured terminating newlines where they were missing * Fix inaccurate/incorrect documentation Mostly this relates to places where timestamps are incorrectly labeled as either RFC or non-RFC, but also includes an unnecessary versionadded directive, incorrect response types, * Grammar fixes, add term links, add response field description * Fix bad automatic merge changes
apache · Sep 28, 2023 · e245f95 · e245f95
1 parent 806b0d0
commit e245f95
Show file tree

Hide file tree

Showing 62 changed files with 650 additions and 358 deletions.
diff --git a/docs/source/admin/traffic_ops.rst b/docs/source/admin/traffic_ops.rst
@@ -328,7 +328,7 @@ This file deals with the configuration parameters of running Traffic Ops itself.
 
 :default_certificate_info: This is an optional object to define default values when generating a self signed certificate when an HTTPS delivery service is created or updated. If this is an empty object or not present in the :ref:`cdn.conf` then the term "Placeholder" will be used for all fields.
 
- 	:business_unit: An optional field which, if present, will represent the business unit for which the SSL certificate was generated
+	:business_unit: An optional field which, if present, will represent the business unit for which the SSL certificate was generated
 	:city: An optional field which, if present, will represent the resident city of the generated SSL certificate
 	:organization: An optional field which, if present, will represent the organization for which the SSL certificate was generated
 	:country: An optional field which, if present, will represent the resident country of the generated SSL certificate

diff --git a/docs/source/api/v3/statuses.rst b/docs/source/api/v3/statuses.rst
@@ -106,8 +106,8 @@ Creates a Server :term:`Status`.
 
 Request Structure
 -----------------
-:description:	Create a :term:`Status` with this description
-:name:			Create a :term:`Status` with this name
+:description: Create a :term:`Status` with this description
+:name:        Create a :term:`Status` with this name
 
 .. code-block:: http
 	:caption: Request Example

diff --git a/docs/source/api/v3/statuses_id.rst b/docs/source/api/v3/statuses_id.rst
@@ -107,8 +107,8 @@ Updates a :term:`Status`.
 
 Request Structure
 -----------------
-:description:	The description of the updated :term:`Status`
-:name:			The name of the updated :term:`Status`
+:description: The description of the updated :term:`Status`
+:name:        The name of the updated :term:`Status`
 
 .. code-block:: http
 	:caption: Request Example

diff --git a/docs/source/api/v3/topologies.rst b/docs/source/api/v3/topologies.rst
@@ -55,7 +55,7 @@ Response Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group`
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Response Example
@@ -161,7 +161,7 @@ Request Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group` with at least 1 server in it
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Request Example
@@ -251,7 +251,7 @@ Response Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group`
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Response Example
@@ -369,7 +369,7 @@ Request Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group` with at least 1 server in it
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Request Example
@@ -451,7 +451,7 @@ Response Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group`
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Response Example

diff --git a/docs/source/api/v4/cdn_notifications.rst b/docs/source/api/v4/cdn_notifications.rst
@@ -57,7 +57,7 @@ Response Structure
 ------------------
 :id:           The integral, unique identifier of the notification
 :cdn:          The name of the CDN to which the notification belongs to
-:lastUpdated:  The time and date this server entry was last updated in :ref:`non-rfc-datetime`
+:lastUpdated:  The time and date this server entry was last updated in :rfc:`3339` format
 :notification: The content of the notification
 :user:         The user responsible for creating the notification
 
@@ -81,7 +81,7 @@ Response Structure
 		{
 			"id": 42,
 			"cdn": "cdn1",
-			"lastUpdated": "2019-12-02 21:49:08+00",
+			"lastUpdated": "2019-12-02T21:49:08Z",
 			"notification": "the content of the notification",
 			"user": "username123",
 		}
@@ -121,7 +121,7 @@ Response Structure
 ------------------
 :id:           The integral, unique identifier of the notification
 :cdn:          The name of the CDN to which the notification belongs to
-:lastUpdated:  The time and date this server entry was last updated in :ref:`non-rfc-datetime`
+:lastUpdated:  The time and date this server entry was last updated in :rfc:`3339` format
 :notification: The content of the notification
 :user:         The user responsible for creating the notification
 
@@ -153,7 +153,7 @@ Response Structure
 		{
 			"id": 42,
 			"cdn": "cdn1",
-			"lastUpdated": "2019-12-02 21:49:08+00",
+			"lastUpdated": "2019-12-02T21:49:08Z",
 			"notification": "the content of the notification",
 			"user": "username123",
 		}

diff --git a/docs/source/api/v4/cdns.rst b/docs/source/api/v4/cdns.rst
@@ -67,7 +67,7 @@ Response Structure
 :id:            The integral, unique identifier for the CDN
 :lastUpdated:   Date and time when the CDN was last modified in :ref:`non-rfc-datetime`
 :name:          The name of the CDN
-:ttlOverride:	A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
+:ttlOverride:   A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
 
 	.. versionadded:: 4.1
 
@@ -119,7 +119,7 @@ Request Structure
 :dnssecEnabled: If ``true``, this CDN will use DNSSEC, if ``false`` it will not
 :domainName:    The top-level domain (TLD) belonging to the new CDN
 :name:          Name of the new CDN
-:ttlOverride:	Optional an nullable. A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
+:ttlOverride:   Optional an nullable. A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
 
 	.. versionadded:: 4.1
 
@@ -142,7 +142,7 @@ Response Structure
 :domainName:    The top-level domain (TLD) assigned to the newly created CDN
 :id:            An integral, unique identifier for the newly created CDN
 :name:          The newly created CDN's name
-:ttlOverride:	A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
+:ttlOverride:   A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
 
 	.. versionadded:: 4.1
 

diff --git a/docs/source/api/v4/cdns_id.rst b/docs/source/api/v4/cdns_id.rst
@@ -41,7 +41,7 @@ Request Structure
 :dnssecEnabled: If ``true``, this CDN will use DNSSEC, if ``false`` it will not
 :domainName:    The top-level domain (TLD) belonging to the CDN
 :name:          Name of the new CDN
-:ttlOverride:	Optional an nullable. A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
+:ttlOverride:   A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`. If this is not present in the request, it will be treated as though it were ``null``.
 
 	.. versionadded:: 4.1
 
@@ -64,7 +64,7 @@ Response Structure
 :domainName:    The top-level domain (TLD) assigned to the newly created CDN
 :id:            An integral, unique identifier for the newly created CDN
 :name:          The newly created CDN's name
-:ttlOverride:	A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`
+:ttlOverride:   A :abbr:`TTL (Time To Live)` value, in seconds, that, if set, overrides all set TTL values on :term:`Delivery Services` in this :abbr:`CDN (Content Delivery Network)`. If this is not present in the request, it will be treated as though it were ``null``.
 
 	.. versionadded:: 4.1
 

diff --git a/docs/source/api/v4/deliveryserviceserver.rst b/docs/source/api/v4/deliveryserviceserver.rst
@@ -65,7 +65,7 @@ Unlike most API endpoints, this will return a JSON response body containing both
 :response: An array of objects, each of which represents a server's :term:`Delivery Service` assignment
 
 	:deliveryService: The integral, unique identifier of the :term:`Delivery Service` to which the server identified by ``server`` is assigned
-	:lastUpdated:     The date and time at which the server's assignment to a :term:`Delivery Service` was last updated
+	:lastUpdated:     The date and time at which the server's assignment to a :term:`Delivery Service` was last updated, in :ref:`non-rfc-datetime`
 	:server:          The integral, unique identifier of a server which is assigned to the :term:`Delivery Service` identified by ``deliveryService``
 
 :size: The page number - if pagination was requested in the query parameters, else ``0`` to indicate no pagination - of the results represented by the ``response`` array. This is named "size" for legacy reasons

diff --git a/docs/source/api/v4/origins.rst b/docs/source/api/v4/origins.rst
@@ -89,7 +89,7 @@ Response Structure
 :ip6Address:        The IPv6 address of the :term:`Origin`
 :ipAddress:         The IPv4 address of the :term:`Origin`
 :isPrimary:         A boolean value which, when ``true`` specifies this :term:`Origin` as the 'primary' :term:`Origin` served by ``deliveryService``
-:lastUpdated:       The date and time at which this :term:`Origin` was last modified
+:lastUpdated:       The date and time at which this :term:`Origin` was last modified, in :ref:`non-rfc-datetime`
 :name:              The name of the :term:`Origin`
 :port:              The TCP port on which the :term:`Origin` listens
 :profile:           The :ref:`profile-name` of the :term:`Profile` used by this :term:`Origin`

diff --git a/docs/source/api/v4/staticdnsentries.rst b/docs/source/api/v4/staticdnsentries.rst
@@ -89,7 +89,7 @@ Response Structure
 :deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
 :host:              If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address``
 :id:                An integral, unique identifier for this static DNS entry
-:lastUpdated:       The date and time at which this static DNS entry was last updated
+:lastUpdated:       The date and time at which this static DNS entry was last updated, in :ref:`non-rfc-datetime`
 :ttl:               The :abbr:`TTL (Time To Live)` of this static DNS entry in seconds
 :type:              The name of the type of this static DNS entry
 :typeId:            The integral, unique identifier of the :term:`Type` of this static DNS entry

diff --git a/docs/source/api/v4/statuses.rst b/docs/source/api/v4/statuses.rst
@@ -107,8 +107,8 @@ Creates a Server :term:`Status`.
 
 Request Structure
 -----------------
-:description:	Create a :term:`Status` with this description
-:name:			Create a :term:`Status` with this name
+:description: Create a :term:`Status` with this description
+:name:        Create a :term:`Status` with this name
 
 .. code-block:: http
 	:caption: Request Example

diff --git a/docs/source/api/v4/statuses_id.rst b/docs/source/api/v4/statuses_id.rst
@@ -107,8 +107,8 @@ Updates a :term:`Status`.
 
 Request Structure
 -----------------
-:description:	The description of the updated :term:`Status`
-:name:			The name of the updated :term:`Status`
+:description: The description of the updated :term:`Status`
+:name:        The name of the updated :term:`Status`
 
 .. code-block:: http
 	:caption: Request Example

diff --git a/docs/source/api/v4/topologies.rst b/docs/source/api/v4/topologies.rst
@@ -56,7 +56,7 @@ Response Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group`
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Response Example
@@ -163,7 +163,7 @@ Request Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group` with at least 1 server in it
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Request Example
@@ -253,7 +253,7 @@ Response Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group`
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Response Example
@@ -372,7 +372,7 @@ Request Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group` with at least 1 server in it
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Request Example
@@ -454,7 +454,7 @@ Response Structure
 :nodes:                 An array of nodes in the :term:`Topology`
 
 	:cachegroup:            The name of a :term:`Cache Group`
-	:parents:               The indices of the parents of this node in the nodes array, 0-indexed. 
+	:parents:               The indices of the parents of this node in the nodes array, 0-indexed.
 
 .. code-block:: http
 	:caption: Response Example

diff --git a/docs/source/api/v5/acme_accounts_provider_email.rst b/docs/source/api/v5/acme_accounts_provider_email.rst
@@ -19,16 +19,14 @@
 ``acme_accounts/{{provider}}/{{email}}``
 ****************************************
 
-.. versionadded:: 3.1
-
 ``DELETE``
 ==========
 Delete :term:`ACME Account` information.
 
 :Auth. Required: Yes
 :Roles Required: "admin"
 :Permissions Required: ACME:DELETE, ACME:READ
-:Response Type:  Object
+:Response Type:  ``undefined``
 
 Request Structure
 -----------------

diff --git a/docs/source/api/v5/asns.rst b/docs/source/api/v5/asns.rst
@@ -76,6 +76,9 @@ Response Structure
 :id:           An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group`
 :lastUpdated:  The time and date this server entry was last updated in :rfc:`3339` Format
 
+	.. versionchanged:: 5.0
+		Prior to version 5.0 of the API, this field was in :ref:`non-rfc-datetime`.
+
 .. code-block:: http
 	:caption: Response Example
 
@@ -146,6 +149,9 @@ Response Structure
 :id:           An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group`
 :lastUpdated:  The time and date this server entry was last updated in :rfc:`3339` Format
 
+	.. versionchanged:: 5.0
+		Prior to version 5.0 of the API, this field was in :ref:`non-rfc-datetime`.
+
 .. code-block:: http
 	:caption: Response Example
 
@@ -216,6 +222,9 @@ Response Structure
 :id:           An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group`
 :lastUpdated:  The time and date this server entry was last updated in :rfc:`3339` Format
 
+	.. versionchanged:: 5.0
+		Prior to version 5.0 of the API, this field was in :ref:`non-rfc-datetime`.
+
 .. code-block:: http
 	:caption: Response Example
 

diff --git a/docs/source/api/v5/asns_id.rst b/docs/source/api/v5/asns_id.rst
@@ -70,6 +70,9 @@ Response Structure
 :id:           An integral, unique identifier for this association between an :abbr:`ASN (Autonomous System Number)` and a :term:`Cache Group`
 :lastUpdated:  The time and date this server entry was last updated in :ref:`non-rfc-datetime`
 
+	.. versionchanged:: 5.0
+		Prior to version 5.0 of the API, this field was in :ref:`non-rfc-datetime`.
+
 .. code-block:: http
 	:caption: Response Example
 

diff --git a/docs/source/api/v5/cachegroups.rst b/docs/source/api/v5/cachegroups.rst
@@ -68,10 +68,14 @@ Request Structure
 
 Response Structure
 ------------------
-:fallbacks:                     An array of strings that are :ref:`Cache Group names <cache-group-name>` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_
-:fallbackToClosest:             A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_
-:id:                            An integer that is the :ref:`cache-group-id` of the :term:`Cache Group`
-:lastUpdated:                   The time and date at which this entry was last updated in :rfc:`3339`
+:fallbacks:         An array of strings that are :ref:`Cache Group names <cache-group-name>` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_
+:fallbackToClosest: A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_
+:id:                An integer that is the :ref:`cache-group-id` of the :term:`Cache Group`
+:lastUpdated:       The time and date at which this entry was last updated in :rfc:`3339`
+
+	.. versionchanged:: 5.0
+		Prior to version 5.0 of the API, this field was in :ref:`non-rfc-datetime`.
+
 :latitude:                      A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group`
 :localizationMethods:           An array of :ref:`cache-group-localization-methods` as strings
 :longitude:                     A floating-point :ref:`cache-group-longitude` for the :term:`Cache Group`
@@ -138,8 +142,8 @@ Request Structure
 
 	.. note:: The default value of ``fallbackToClosest`` is ``true``, and if it is ``null`` Traffic Control components will still interpret it as though it were ``true``.
 
-:latitude:                    An optional field which, if present, should be a floating-point number that will define the :ref:`cache-group-latitude` for the :term:`Cache Group`\ [#optional]_
-:localizationMethods:         Array of :ref:`cache-group-localization-methods` (as strings)
+:latitude:            An optional field which, if present, should be a floating-point number that will define the :ref:`cache-group-latitude` for the :term:`Cache Group`\ [#optional]_
+:localizationMethods: Array of :ref:`cache-group-localization-methods` (as strings)
 
 	.. tip:: This field has no defined meaning if the :ref:`cache-group-type` identified by ``typeId`` is not "EDGE_LOC".
 
@@ -179,10 +183,14 @@ Request Structure
 
 Response Structure
 ------------------
-:fallbacks:                     An array of strings that are :ref:`Cache Group names <cache-group-name>` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_
-:fallbackToClosest:             A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_
-:id:                            An integer that is the :ref:`cache-group-id` of the :term:`Cache Group`
-:lastUpdated:                   The time and date at which this entry was last updated in :rfc:`3339`
+:fallbacks:         An array of strings that are :ref:`Cache Group names <cache-group-name>` that are registered as :ref:`cache-group-fallbacks` for this :term:`Cache Group`\ [#fallbacks]_
+:fallbackToClosest: A boolean value that defines the :ref:`cache-group-fallback-to-closest` behavior of this :term:`Cache Group`\ [#fallbacks]_
+:id:                An integer that is the :ref:`cache-group-id` of the :term:`Cache Group`
+:lastUpdated:       The time and date at which this entry was last updated in :rfc:`3339`
+
+	.. versionchanged:: 5.0
+		Prior to version 5.0 of the API, this field was in :ref:`non-rfc-datetime`.
+
 :latitude:                      A floating-point :ref:`cache-group-latitude` for the :term:`Cache Group`
 :localizationMethods:           An array of :ref:`cache-group-localization-methods` as strings
 :longitude:                     A floating-point :ref:`cache-group-longitude` for the :term:`Cache Group`