Fix the documentation build (#5704)

In #5678, I thought that the extra README that eventually ended up in
`cvat-sdk/docs/README.md` was unused, which turned out to be not quite
true. One section from it _was_ used to generate the online API index
page. Since I removed the file, the online docs now fail to build.

Rather than restore the entire README, restore just that one section as
a standalone file. This achieves the same result as before, but with
simpler code.

cvat-sdk/gen/generate.sh

@@ -12,11 +12,12 @@ VERSION="2.3.0"
 LIB_NAME="cvat_sdk"
 LAYER1_LIB_NAME="${LIB_NAME}/api_client"
 DST_DIR="$(cd "$(dirname -- "$0")/.." && pwd)"
+DOCS_DIR="$DST_DIR/docs"
 TEMPLATE_DIR_NAME="gen"
 TEMPLATE_DIR="$DST_DIR/$TEMPLATE_DIR_NAME"
 POST_PROCESS_SCRIPT="${TEMPLATE_DIR}/postprocess.py"
 
-rm -f -r "${DST_DIR}/docs" "${DST_DIR}/${LAYER1_LIB_NAME}" \
+rm -f -r "$DOCS_DIR" "${DST_DIR}/${LAYER1_LIB_NAME}" \
     "${DST_DIR}/requirements/api_client.txt"
 
 # Pass template dir here
@@ -33,17 +34,19 @@ docker run --rm -v "$DST_DIR:/local" -u "$(id -u)":"$(id -g)" \
 echo "VERSION = \"$VERSION\"" > "${DST_DIR}/${LIB_NAME}/version.py"
 mv "${DST_DIR}/requirements.txt" "${DST_DIR}/requirements/api_client.txt"
 
+API_DOCS_DIR="${DOCS_DIR}/apis/"
+MODEL_DOCS_DIR="${DOCS_DIR}/models/"
+mkdir "${API_DOCS_DIR}"
+mkdir "${MODEL_DOCS_DIR}"
+mv "${DOCS_DIR}/"*Api.md "${API_DOCS_DIR}"
+mv "${DOCS_DIR}/"*.md "${MODEL_DOCS_DIR}"
+mv "${DST_DIR}/api_summary.md" "${DOCS_DIR}"
+
 # Do custom postprocessing for code files
 "${POST_PROCESS_SCRIPT}" --schema "${DST_DIR}/schema/schema.yml" \
     --input-path "${DST_DIR}/${LIB_NAME}"
 
 # Do custom postprocessing for docs files
 "${POST_PROCESS_SCRIPT}" --schema "${DST_DIR}/schema/schema.yml" \
-    --input-path "${DST_DIR}/docs" --file-ext '.md'
+    --input-path "$DOCS_DIR" --file-ext '.md'
 
-API_DOCS_DIR="${DST_DIR}/docs/apis/"
-MODEL_DOCS_DIR="${DST_DIR}/docs/models/"
-mkdir "${API_DOCS_DIR}"
-mkdir "${MODEL_DOCS_DIR}"
-mv "${DST_DIR}/docs/"*Api.md "${API_DOCS_DIR}"
-mv "${DST_DIR}/docs/"*.md "${MODEL_DOCS_DIR}"

cvat-sdk/gen/generator-config.yml

@@ -9,3 +9,6 @@ globalProperties:
   generateAliasAsModel: true
   apiTests: false
   modelTests: false
+files:
+  api_summary.mustache:
+    destinationFilename: api_summary.md

cvat-sdk/gen/templates/openapi-generator/api_summary.mustache

@@ -0,0 +1,6 @@
+All URIs are relative to _{{basePath}}_
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}_{{classname}}_ | [**{{>operation_name}}**](apis/{{classname}}#{{>operation_name}}) | **{{httpMethod}}** {{path}} | {{summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}

site/process_sdk_docs.py

@@ -84,19 +84,6 @@ class Processor:
             with open(p, "w") as f:
                 f.write(contents)
 
-    def _extract_apis_summary(self, readme_path: str) -> str:
-        with open(readme_path) as f:
-            readme_contents = f.read()
-
-        apis_summary = re.search(
-            r"## Available API Endpoints(.*)## Available Models",
-            readme_contents,
-            flags=re.DOTALL,
-        )[1]
-        assert len(apis_summary) > 0
-
-        return apis_summary
-
     def _move_api_summary(self):
         """
         Moves API summary section from README to apis/_index
@@ -104,9 +91,8 @@ class Processor:
 
         SUMMARY_REPLACE_TOKEN = "{{REPLACEME:apis_summary}}"  # nosec
 
-        apis_summary = self._extract_apis_summary(
+        with open(osp.join(self._input_dir, "api_summary.md")) as f:
-            osp.join(self._input_dir, "README.md")
+            apis_summary = f.read()
-        )
 
         apis_index_filename = osp.join(
             osp.relpath(self._sdk_reference_dir, self._content_dir), "apis/_index.md"