test sphinx-contrib/redoc

build.sh

@@ -62,13 +62,13 @@ set -e
     #    exit 1
     #fi 
 
+# Update JSON specs 
+    ./update-redoc.py
+
 # Build docs
     cd $DIR_BASE
     make html SPHINXBUILD="python ${DIR_ENV}/bin/sphinx-build"
 
-# Update JSON specs 
-    ./update-redoc.py
-
 # Create TAR
     if [[ ! -d "$DIR_BASE/output/" ]]; then 
         mkdir $DIR_BASE/output/

requirements.txt

@@ -17,4 +17,5 @@ sphinxcontrib-youtube
 virtualenv
 sphinx-jsonschema==1.19.1
 requests
-ods-tools
+ods-tools
+sphinxcontrib-redoc

src/conf.py

@@ -60,6 +60,7 @@
     'sphinx.ext.mathjax',
     "sphinxcontrib.youtube",
     # 'autoapi.extension',
+    'sphinxcontrib.redoc',
 ]
 
 autoapi_dirs = [
@@ -224,6 +225,50 @@
 ]
 
 
+# -- Redoc ------------------------------------------------------------------
+#
+#redoc_uri = 'https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js'
+redoc_uri = 'https://cdn.redoc.ly/redoc/v2.0.0/bundles/redoc.standalone.js'
+redoc = [
+    {
+        'name': 'Analysis Settings',
+        'page': 'sections/analysis_settings',
+        'spec': 'schema/analysis_settings.json',
+        'embed': False,
+    },
+    {
+        'name': 'Model Settings',
+        'page': 'sections/model_settings',
+        'spec': 'schema/model_settings.json',
+        'embed': False,
+    },
+    {
+        'name': 'Platform 1 API',
+        'page': 'sections/platform_1',
+        'spec': 'schema/platform-1.json',
+        'embed': True,
+    },
+    {
+        'name': 'Platform 2 API',
+        'page': 'sections/platform_2',
+        'spec': 'schema/platform-2.json',
+        'embed': True,
+    },
+]
+    # Example, note: a placeholder rst file is needed matching 'page' with just a title
+    #{
+    #    'name': 'Example API',
+    #    'page': 'example/index',
+    #    'spec': 'http://example.com/openapi.yml',
+    #    'opts': {
+    #        'lazy': False,
+    #        'nowarnings': False,
+    #        'nohostname': False,
+    #        'required-props-first': True,
+    #        'expand-responses': ["200", "201"],
+    #    }
+    #},
+
 # -- Extension configuration -------------------------------------------------
 
 # -- Options for intersphinx extension ---------------------------------------

src/index.rst

@@ -82,8 +82,10 @@ It allows regression of the models after updates to the Oasis Platform code, and
     :titlesonly:
     :caption: Sections:
 
-    sections/analysis-settings.rst
-    analysis_settings_test <https://oasislmf.github.io/PreviewDocs/pr-preview/pr-10/schema/analysis_settings/index.html>
+    sections/analysis_settings
+    sections/model_settings
+    sections/platform_1
+    sections/platform_2
     sections/API.rst
     sections/camel.rst
     sections/deployment.rst
@@ -113,9 +115,7 @@ It allows regression of the models after updates to the Oasis Platform code, and
     sections/releases.rst
     sections/results.rst
     sections/SaaS-providers.rst
-
-
+
 .. 
   sections to be populated: sections/pre-analysis-adjustments.rst, sections/sampling-methodology.rst, sections/errors.rst
 
-

src/sections/analysis_settings.rst

@@ -0,0 +1,2 @@
+Analysis Settings
+=================

src/sections/model_settings.rst

@@ -0,0 +1,2 @@
+Model Settings
+==============

src/sections/platform_1.rst

@@ -0,0 +1,2 @@
+Platform 1 API
+==============

src/sections/platform_2.rst

@@ -0,0 +1,2 @@
+Platform 2 API
+==============

update-redoc.py

@@ -10,10 +10,10 @@
 from ods_tools.oed.setting_schema import ModelSettingSchema, AnalysisSettingSchema
 
 # Locations
-MODEL_SETTINGS_SCHEMA = './schema/model_settings/model_schema.json'
-ANALYSIS_SETTING_SCHEMA = './schema/analysis_settings/analysis_schema.json'
-PLAT_V1_SCHEMA = './schema/v1/oasis-platform-schema.json'
-PLAT_V2_SCHEMA = './schema/v2/oasis-platform-schema.json'
+MODEL_SETTINGS_SCHEMA = './src/schema/model_settings.json'
+ANALYSIS_SETTING_SCHEMA = './src/schema/analysis_settings.json'
+PLAT_V1_SCHEMA = './src/schema/platform-1.json'
+PLAT_V2_SCHEMA = './src/schema/platform-2.json'
 
 # urls
 PLAT_V1_VER = '1.8.0'
@@ -60,23 +60,23 @@ def patch_schema(base_schema, version, description):
 plat_2_desc = read_file('./schema/v2/description.md').decode()
 write_json(PLAT_V2_SCHEMA, patch_schema(plat_2_schema, PLAT_V2_VER ,plat_2_desc))
 
-# Docker build arguments
-docker_basecmd = ['docker', 'run', '--rm', '-v', f'{os.getcwd()}:/spec', "--user", f"{os.getuid()}", 'redocly/cli', 'build-docs']
-theme_args = ['--theme.openapi.fontFamily', 'Raleway'] # https://redocly.com/docs/api-reference-docs/configuration/theming/
-build_args = [
-    [MODEL_SETTINGS_SCHEMA, '--output', 'build/html/schema/model_settings/index.html'],
-    [ANALYSIS_SETTING_SCHEMA, '--output', 'build/html/schema/analysis_settings/index.html'],
-    [PLAT_V1_SCHEMA, '--output', 'build/html/schema/v1/index.html'],
-    [PLAT_V2_SCHEMA, '--output', 'build/html/schema/v2/index.html'],
-]
-
-# Run docker build
-for redoc_build in build_args:
-    exec_docker_cmd = docker_basecmd + redoc_build + theme_args
-    print("Running docker: " + " ".join(exec_docker_cmd))
-
-    result = subprocess.run(exec_docker_cmd, capture_output=True, text=True)
-    print("Standard Output:")
-    print(result.stdout)
-    print("\nStandard Error:")
-    print(result.stderr)
+## Docker build arguments
+#docker_basecmd = ['docker', 'run', '--rm', '-v', f'{os.getcwd()}:/spec', "--user", f"{os.getuid()}", 'redocly/cli', 'build-docs']
+#theme_args = ['--theme.openapi.fontFamily', 'Raleway'] # https://redocly.com/docs/api-reference-docs/configuration/theming/
+#build_args = [
+#    [MODEL_SETTINGS_SCHEMA, '--output', 'build/html/schema/model_settings/index.html'],
+#    [ANALYSIS_SETTING_SCHEMA, '--output', 'build/html/schema/analysis_settings/index.html'],
+#    [PLAT_V1_SCHEMA, '--output', 'build/html/schema/v1/index.html'],
+#    [PLAT_V2_SCHEMA, '--output', 'build/html/schema/v2/index.html'],
+#]
+#
+## Run docker build
+#for redoc_build in build_args:
+#    exec_docker_cmd = docker_basecmd + redoc_build + theme_args
+#    print("Running docker: " + " ".join(exec_docker_cmd))
+#
+#    result = subprocess.run(exec_docker_cmd, capture_output=True, text=True)
+#    print("Standard Output:")
+#    print(result.stdout)
+#    print("\nStandard Error:")
+#    print(result.stderr)