Re-add OpenAPI response content that was lost in migration (#368)

* Delete obsolete Python API docs generator

* Migration script: More conservative strip and replace

Preserve colons and additional paragraphs in API response descriptions

* Add back colons and additional paragraphs to HTTP API responses that were lost

* Mention current limitation of one paragraph per admonition in OpenAPI descriptions

Author: Simran-B

README.md

@@ -344,6 +344,11 @@ paths:
 ```
 ````
 
+For the OpenAPI JSON output, this is rendered as `> **WARNING:** ...`
+(a blockquote with the admonition type in bold and uppercase).
+Only a single paragraph is properly supported by the toolchain. Additional
+paragraphs will not be part of the blockquote.
+
 Admonitions inside of other shortcodes need to use the special syntax, too:
 
 ```markdown

migration-tools/scripts/http_docublocks.py

@@ -204,7 +204,7 @@ def processHTTPDocuBlock(docuBlock, tag, headerLevel):
 
     blocks = re.findall(r"(@RESTRETURNCODE\W.*?)(?=@RESTRETURNCODE|@ENDRESPONSES)",  docuBlock, re.MULTILINE | re.DOTALL)
     for block in blocks:
-        restReturnCode = re.search(r"@RESTRETURNCODE\W(.*?)(?=@|\n\n)", block, re.MULTILINE | re.DOTALL).group(0)
+        restReturnCode = re.search(r"@RESTRETURNCODE\W(.*?)(?=\n@|\Z)", block, re.MULTILINE | re.DOTALL).group(0)
         try:
             currentRetStatus = processResponse(restReturnCode, newBlock["paths"][url][verb])
         except Exception as ex:
@@ -311,7 +311,7 @@ def processParameters(docuBlock, newBlock):
 
     paramBlock["required"] = True if paramSplit[2] == "required" else False
 
-    paramBlock["description"] = "\n".join(docuBlock[1].split("\n")[1:]).replace(":", "") + "\n"
+    paramBlock["description"] = "\n".join(docuBlock[1].split("\n")[1:]) + "\n"
     paramBlock["schema"] = {"type": paramSplit[1]}
     try:
         if paramSplit[3] != "" and not paramSplit[3] in swaggerBaseTypes:
@@ -372,8 +372,8 @@ def processRequestBody(docuBlock, newBlock):
 def processResponse(docuBlock, newBlock):
     blockSplit = docuBlock.split("\n")
     statusRE = re.search(r"\d+}", docuBlock).group(0)
-    description = docuBlock.replace(statusRE, "").replace(":", "").replace("@RESTRETURNCODE{", "") + "\n"
-    status = statusRE.replace("}", "")
+    description = docuBlock.replace(statusRE, "").replace("@RESTRETURNCODE{", "") + "\n"
+    status = statusRE.rstrip("}")
 
     retBlock = {"description": description}
 

migration-tools/scripts/inline_docublocks.py

@@ -35,7 +35,7 @@ def migrateInlineDocuBlocks(block):
 
     datasetRe = re.search(r"@DATASET.*", block)
     if datasetRe:
-        newBlock["options"]["dataset"] = datasetRe.group(0).replace("@DATASET{", "").replace("}", "")
+        newBlock["options"]["dataset"] = datasetRe.group(0).replace("@DATASET{", "").rstrip("}")
         block = re.sub(r" *@DATASET.*\n", '', block)
 
     explainRe = re.search(r"@EXPLAIN\{TRUE\}.*", block)

site/content/3.10/develop/http-api/administration.md

@@ -563,6 +563,11 @@ paths:
           description: |
             HTTP 503 will be returned in case the server is during startup or during shutdown,
             is set to read-only mode or is currently a follower in an Active Failover deployment setup.
+
+            In addition, HTTP 503 will be returned in case the fill grade of the scheduler
+            queue exceeds the configured high-water mark (adjustable via startup option
+            `--server.unavailability-queue-fill-grade`), which by default is set to 75 % of
+            the maximum queue length.
       tags:
         - Administration
 ```
@@ -875,7 +880,7 @@ paths:
           in: query
           required: false
           description: |
-            <small>Introduced in v3.7.12, v3.8.1, v3.9.0</small>
+            <small>Introduced in: v3.7.12, v3.8.1, v3.9.0</small>
 
             If set to `true`, this initiates a soft shutdown. This is only available
             on Coordinators. When issued, the Coordinator tracks a number of ongoing
@@ -890,12 +895,12 @@ paths:
             requests will be handled by the remaining Coordinators, reducing the designated
             Coordinator's load.
 
-            The following types of operations are tracked
+            The following types of operations are tracked:
 
              - AQL cursors (in particular streaming cursors)
              - Transactions (in particular stream transactions)
              - Pregel runs (conducted by this Coordinator)
-             - Ongoing asynchronous requests (using the `x-arango-async store` HTTP header)
+             - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header)
              - Finished asynchronous requests, whose result has not yet been
                collected
              - Queued low priority requests (most normal requests)
@@ -1336,9 +1341,11 @@ paths:
         the only attribute, and with the value being a string describing the
         endpoint.
 
-        **Note**: retrieving the array of all endpoints is allowed in the system database
+        {{</* info */>}}
+        Retrieving the array of all endpoints is allowed in the system database
         only. Calling this action in any other database will make the server return
         an error.
+        {{</* /info */>}}
       responses:
         '200':
           description: |

site/content/3.10/develop/http-api/collections.md

@@ -505,7 +505,7 @@ paths:
       responses:
         '200':
           description: |
-            Returns information about the collection
+            Returns information about the collection:
           content:
             application/json:
               schema:
@@ -615,7 +615,9 @@ paths:
         The response is a JSON object with a `shardId` attribute, which will
         contain the ID of the responsible shard.
 
-        **Note** : This method is only available in a cluster Coordinator.
+        {{</* info */>}}
+        This method is only available on Coordinators in cluster deployments.
+        {{</* /info */>}}
       requestBody:
         content:
           application/json:
@@ -695,7 +697,9 @@ paths:
         shard IDs as object attribute keys, and the responsible servers for each shard mapped to them.
         In the detailed response, the leader shards will be first in the arrays.
 
-        **Note** : This method is only available in a cluster Coordinator.
+        {{</* info */>}}
+        This method is only available on Coordinators in cluster deployments.
+        {{</* /info */>}}
       parameters:
         - name: collection-name
           in: path
@@ -858,7 +862,10 @@ paths:
 
         By providing the optional query parameter `withData` with a value of `true`,
         the user-defined document attributes will be included in the calculation too.
-        **Note**: Including user-defined attributes will make the checksumming slower.
+
+        {{</* info */>}}
+        Including user-defined attributes will make the checksumming slower.
+        {{</* /info */>}}
 
         The response is a JSON object with the following attributes:
 
@@ -1127,8 +1134,7 @@ paths:
                 numberOfShards:
                   description: |
                     (The default is `1`): in a cluster, this value determines the
-                    number of shards to create for the collection. In a single
-                    server setup, this option is meaningless.
+                    number of shards to create for the collection.
                   type: integer
                 shardKeys:
                   description: |
@@ -1137,8 +1143,10 @@ paths:
                     Documents are sent to shards based on the values of their shard key attributes.
                     The values of all shard key attributes in a document are hashed,
                     and the hash value is used to determine the target shard.
-                    **Note**: Values of shard key attributes cannot be changed once set.
-                      This option is meaningless in a single server setup.
+                    
+                    {{</* info */>}}
+                    The values of shard key attributes cannot be changed once set.
+                    {{</* /info */>}}
                   type: string
                 replicationFactor:
                   description: |
@@ -1212,11 +1220,13 @@ paths:
 
                     The default is `""`.
 
-                    **Note**: Using this parameter has consequences for the prototype
+                    {{</* info */>}}
+                    Using this parameter has consequences for the prototype
                     collection. It can no longer be dropped, before the sharding-imitating
                     collections are dropped. Equally, backups and restores of imitating
                     collections alone generate warnings (which can be overridden)
                     about a missing sharding prototype.
+                    {{</* /info */>}}
                   type: string
                 isSmart:
                   description: |
@@ -1684,7 +1694,7 @@ paths:
           required: false
           description: |
             If `true` then the data is synchronized to disk before returning from the
-            truncate operation (default `false`)
+            truncate operation (default: `false`)
           schema:
             type: boolean
         - name: compact
@@ -2164,7 +2174,9 @@ paths:
         If renaming the collection succeeds, then the collection is also renamed in
         all graph definitions inside the `_graphs` collection in the current database.
 
-        **Note**: this method is not available in a cluster.
+        {{</* info */>}}
+        Renaming collections is not supported in cluster deployments.
+        {{</* /info */>}}
       parameters:
         - name: collection-name
           in: path

site/content/3.10/develop/http-api/databases.md

@@ -153,7 +153,9 @@ paths:
       description: |
         Retrieves the list of all existing databases
 
-        **Note**: retrieving the list of databases is only possible from within the `_system` database.
+        {{</* info */>}}
+        Retrieving the list of databases is only possible from within the `_system` database.
+        {{</* /info */>}}
       responses:
         '200':
           description: |
@@ -195,7 +197,9 @@ paths:
 
         The response is a JSON object with the attribute `result` set to `true`.
 
-        **Note**: Creating a new database is only possible from within the `_system` database.
+        {{</* info */>}}
+        Creating a new database is only possible from within the `_system` database.
+        {{</* /info */>}}
       requestBody:
         content:
           application/json:
@@ -374,8 +378,10 @@ paths:
       description: |
         Drops the database along with all data stored in it.
 
-        **Note**: dropping a database is only possible from within the `_system` database.
+        {{</* info */>}}
+        Dropping a database is only possible from within the `_system` database.
         The `_system` database itself cannot be dropped.
+        {{</* /info */>}}
       parameters:
         - name: database-name
           in: path

site/content/3.10/develop/http-api/documents.md

@@ -435,21 +435,21 @@ paths:
           in: query
           required: false
           description: |
-            This option supersedes `overwrite` and offers the following modes
-            - `"ignore"` if a document with the specified `_key` value exists already,
+            This option supersedes `overwrite` and offers the following modes:
+            - `"ignore"`: if a document with the specified `_key` value exists already,
               nothing is done and no write operation is carried out. The
               insert operation returns success in this case. This mode does not
               support returning the old document version using `RETURN OLD`. When using
               `RETURN NEW`, `null` is returned in case the document already existed.
-            - `"replace"` if a document with the specified `_key` value exists already,
+            - `"replace"`: if a document with the specified `_key` value exists already,
               it is overwritten with the specified document value. This mode is
               also used when no overwrite mode is specified but the `overwrite`
               flag is set to `true`.
-            - `"update"` if a document with the specified `_key` value exists already,
+            - `"update"`: if a document with the specified `_key` value exists already,
               it is patched (partially updated) with the specified document value.
               The overwrite mode can be further controlled via the `keepNull` and
               `mergeObjects` parameters.
-            - `"conflict"` if a document with the specified `_key` value exists already,
+            - `"conflict"`: if a document with the specified `_key` value exists already,
               return a unique constraint violation error so that the insert operation
               fails. This is also the default behavior in case the overwrite mode is
               not set, and the `overwrite` flag is `false` or not set either.
@@ -1473,7 +1473,7 @@ paths:
           in: query
           required: false
           description: |
-            Should the value be `true` (the default)
+            Should the value be `true` (the default):
             If a search document contains a value for the `_rev` field,
             then the document is only returned if it has the same revision value.
             Otherwise a precondition failed error is returned.
@@ -1673,21 +1673,21 @@ paths:
           in: query
           required: false
           description: |
-            This option supersedes `overwrite` and offers the following modes
-            - `"ignore"` if a document with the specified `_key` value exists already,
+            This option supersedes `overwrite` and offers the following modes:
+            - `"ignore"`: if a document with the specified `_key` value exists already,
               nothing is done and no write operation is carried out. The
               insert operation returns success in this case. This mode does not
               support returning the old document version using `RETURN OLD`. When using
               `RETURN NEW`, `null` is returned in case the document already existed.
-            - `"replace"` if a document with the specified `_key` value exists already,
+            - `"replace"`: if a document with the specified `_key` value exists already,
               it is overwritten with the specified document value. This mode is
               also used when no overwrite mode is specified but the `overwrite`
               flag is set to `true`.
-            - `"update"` if a document with the specified `_key` value exists already,
+            - `"update"`: if a document with the specified `_key` value exists already,
               it is patched (partially updated) with the specified document value.
               The overwrite mode can be further controlled via the `keepNull` and
               `mergeObjects` parameters.
-            - `"conflict"` if a document with the specified `_key` value exists already,
+            - `"conflict"`: if a document with the specified `_key` value exists already,
               return a unique constraint violation error so that the insert operation
               fails. This is also the default behavior in case the overwrite mode is
               not set, and the `overwrite` flag is `false` or not set either.