Merge pull request canonical#149 from keirthana/automate-api-reference

Automate loading of AMS and Gateway API spec from swagger

.gitignore

@@ -14,3 +14,5 @@ __pycache__
 .vscode/
 .sphinx/styles/*
 .sphinx/vale.ini
+.sphinx/deps/
+.sphinx/_static/swagger-ui/

.sphinx/_extra/ams-api.yaml

@@ -0,0 +1 @@
+../../reference/api-reference/ams-api.yaml

.sphinx/_extra/gateway-api.yaml

@@ -0,0 +1 @@
+../../reference/api-reference/gateway-api.yaml

custom_conf.py

@@ -1,4 +1,7 @@
 import datetime
+import os
+import subprocess
+
 
 # Custom configuration for the Sphinx documentation builder.
 # All configuration specific to your project should be done in this file.
@@ -216,3 +219,38 @@
 .. role:: center
    :class: align-center
 '''
+
+## Generate dynamic configuration using scripts
+# Inject AMS configuration valuues and Node configuration values from the swagger
+# specification hosted on Github.
+def generate_ams_configuration():
+    from scripts.ams_configuration import get_swagger_from_url, parse_swagger
+
+    with open("scripts/requirements.txt", "r") as f:
+        for req in f.readlines():
+            custom_required_modules.append(req)
+    ams_configuration_file = "reference/ams-configuration.md"
+    parse_swagger(get_swagger_from_url(), ams_configuration_file)
+
+## The following code is to automatically load the API from swagger into documentation.
+
+# Path to copy the YAML files during build
+html_extra_path = ['.sphinx/_extra']
+
+# The swagger-ui repository is required to be able to render the swagger YAML
+# file as browseable API documentation. The below variable specifies which
+# git repository to fetch it from.
+swagger_ui_repository = "https://github.com/swagger-api/swagger-ui"
+
+# Download and link swagger-ui files
+if not os.path.isdir('.sphinx/deps/swagger-ui'):
+    subprocess.check_call(["git", "clone", "--depth=1", swagger_ui_repository, ".sphinx/deps/swagger-ui"])
+
+os.makedirs('.sphinx/_static/swagger-ui/', exist_ok=True)
+
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-bundle.js'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui-bundle.js', '.sphinx/_static/swagger-ui/swagger-ui-bundle.js')
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui-standalone-preset.js', '.sphinx/_static/swagger-ui/swagger-ui-standalone-preset.js')
+if not os.path.islink('.sphinx/_static/swagger-ui/swagger-ui.css'):
+    os.symlink('../../deps/swagger-ui/dist/swagger-ui.css', '.sphinx/_static/swagger-ui/swagger-ui.css')

reference/api-reference/ams-api.md

@@ -0,0 +1,29 @@
+# AMS HTTP API
+
+<link rel="stylesheet" type="text/css" href="../../../_static/swagger-ui/swagger-ui.css" ></link>
+<link rel="stylesheet" type="text/css" href="../../../_static/swagger-override.css" ></link>
+<div id="swagger-ui"></div>
+
+<script src="../../../_static/swagger-ui/swagger-ui-bundle.js" charset="UTF-8"> </script>
+<script src="../../../_static/swagger-ui/swagger-ui-standalone-preset.js" charset="UTF-8"> </script>
+<script>
+window.onload = function() {
+  // Begin Swagger UI call region
+  const ui = SwaggerUIBundle({
+    url: window.location.pathname +"../../../ams-api.yaml",
+    dom_id: '#swagger-ui',
+    deepLinking: true,
+    presets: [
+      SwaggerUIBundle.presets.apis,
+      SwaggerUIStandalonePreset
+    ],
+    plugins: [],
+    validatorUrl: "none",
+    defaultModelsExpandDepth: -1,
+    supportedSubmitMethods: []
+  })
+  // End Swagger UI call region
+
+  window.ui = ui
+}
+</script>