Merge pull request #16 from OasisLMF/feature/update_docs

Feature/update docs

build.sh

@@ -62,6 +62,9 @@ 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"
@@ -72,3 +75,5 @@ set -e
     fi 
     tar -czvf oasis_docs.tar.gz -C build/html/ .
     mv oasis_docs.tar.gz $DIR_BASE/output/
+
+

redoc/analysis_settings/description.md

@@ -0,0 +1,7 @@
+# Analysis Settings Overview
+
+The run time settings for the analysis are controlled by the `analysis_settings.json` file which is a user supplied file detailing all of the options requested for the run (model to run, exposure set to use, number of samples, occurrence options, outputs required, etc.). In the MDK, the analysis settings file must be specified as part of the command line arguments (or in the oasislmf.json configuration file) and in the platform, it needs to be posted to the endpoint. A full json schema for the available options in the analysis settings file can be found here:
+
+https://github.com/OasisLMF/ODS_Tools/blob/develop/ods_tools/data/analysis_settings_schema.json
+
+This is useful for more technical users who are looking to create their own UI or integrate Oasis with an existing system. The `analysis_settings` schema hierarchy is shown in `json` format in right column of the page. An interactive version of the schema, with descriptions and examples, can be found below:

redoc/analysis_settings/redoc_template.json

@@ -0,0 +1,39 @@
+{
+	"openapi": "3.0.0",
+	"info": {
+		"title": "ODS Analysis Settings",
+		"description": "<TEXT HERE>",
+		"version": "<ODS_VERSION>",
+		"x-logo": {
+			"url": "https://oasislmf.github.io/_static/OASIS_LMF_COLOUR.png",
+			"backgroundColor": "#FFFFFF",
+			"altText": "OasisLMF logo"
+		}
+	},
+	"tags": [
+		{
+			"name": "analysis_settings",
+			"x-displayName": "Analysis Settings Schema",
+			"description": "<SchemaDefinition schemaRef=\"#/definitions/AnalysisSettings\" />"
+		},
+		{
+			"name": "landing_page_link",
+			"x-displayName": "Back to landing page",
+			"externalDocs": {
+				"url": "http://oasislmf.github.io/",
+				"description": "Click here to go back to the landing page"
+			}
+		}
+	],
+	"x-tagGroups": [{
+		"name": "JSON Schema",
+		"tags": [
+			"landing_page_link",
+			"analysis_settings"
+		]
+	}],
+
+	"definitions": {
+		"AnalysisSettings": {}
+	}
+}

redoc/model_settings/description.md

@@ -0,0 +1,7 @@
+# Model Settings Overview 
+
+This is a configuration file provided with the model to specify important meta data about the model to model users and systems. It is supplied by the model provider and is a static document. A full specification of the `model_settings` schema can be found here: 
+
+https://github.com/OasisLMF/ODS_Tools/blob/main/ods_tools/data/model_settings_schema.json
+
+This is useful for more technical users who are looking to create their own UI or integrate Oasis with an existing system. The `model_settings` schema hierarchy is shown in `json` format in right column of the page. An interactive version of the schema, with descriptions and examples, can be found below:

redoc/model_settings/redoc_template.json

@@ -0,0 +1,40 @@
+{
+	"openapi": "3.0.0",
+	"info": {
+		"title": "ODS Model Settings",
+		"description": "<TEXT HERE>",
+		"version": "<ODS_VERSION>",
+		"x-logo": {
+			"url": "https://oasislmf.github.io/_static/OASIS_LMF_COLOUR.png",
+			"backgroundColor": "#FFFFFF",
+			"altText": "OasisLMF logo"
+		}
+	},
+
+	"tags": [
+        {
+			"name": "model_settings",
+			"x-displayName": "Model Settings Schema",
+			"description": "<SchemaDefinition schemaRef=\"#/definitions/ModelParameters\" />"
+		},
+		{
+			"name": "landing_page_link",
+			"x-displayName": "Back to landing page",
+			"externalDocs": {
+				"url": "http://oasislmf.github.io/",
+				"description": "Click here to go back to the landing page"
+			}
+		}
+	],
+	"x-tagGroups": [{
+		"name": "JSON Schema",
+		"tags": [
+			"landing_page_link",
+			"model_settings"
+		]
+	}],
+
+	"definitions": {
+		"ModelParameters": {}
+	}
+}

redoc/v1/description.md

@@ -0,0 +1,65 @@
+# Introduction 
+
+Oasis has a full REST API for managing exposure data and operating
+modelling workflows. API Swagger documentation can be found
+[here](http://api.oasislmfdev.org/swagger/). An evaluation version of
+the Oasis platform and using can be deployed using the [Oasis evaluation
+repository](https://github.com/OasisLMF/OasisEvaluation). This includes
+a Jupyter notebook that illustrates the basic operation of the API,
+using the Python API client.
+
+# Oasis API
+
+The Oasis Platform release now includes a full API for operating
+catastrophe models and a general consolidation of the platform
+architecture. Windows SQL server is no longer a strict requirement. The
+platform can be run via docker containers on a single machine or, if
+required, scaled up to run on a cluster.
+
+Docker support is the main requirement for running the platform. A Linux
+based installation is the main focus of this example deployment. Running
+the install script from this repository automates install process of the
+**OasisPlatform API v1**, User Interface and example PiWind model.
+
+The **Oasis API** is the components of the Oasis platform that manages
+all the elements of the plaform that are required to build, run, and
+test models. The diagram below shows how the **Oasis API** sits behind
+the [Oasis-UI](https://oasislmf.github.io/sections/Oasis-UI.html)
+you use to operate your catastrophe models.
+
+*Oasis docker componets*:
+
+<img src="https://raw.githubusercontent.com/OasisLMF/GenerateDocs/feature/update_docs/src/images/oasis_containers.png" alt="Oasis docker componets" style="align-center; width:600px;"/>
+
+# API deployment in the Oasis Enterprise Platform
+
+The **Oasis Enterprise Platform** is supported by the **OasisPlatform API v2**, and is an open source
+[Kubernetes](https://kubernetes.io/docs/concepts/overview/) based, cloud
+computing cluster, which is deployable in [Microsoft Azure](https://azure.microsoft.com/en-gb/resources/cloud-computing-dictionary/what-is-azure/) via 
+[Helm charts](https://helm.sh/docs/topics/charts/) and [Bicep scripts](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deployment-script-bicep)
+to setup the Azure cloud services. The diagram below sets out the
+
+**Oasis Enterprise Platform** architecture:
+
+<img src="https://raw.githubusercontent.com/OasisLMF/GenerateDocs/feature/update_docs/src/images/diag_oasis_components.png" alt="Oasis Enterprise Platform Architecture" style="align-center; width:600px;"/>
+
+# Links for further information
+
+There is more information availible in the [Oasis GitHub](https://github.com/OasisLMF).
+
+This includes detailed walkthorughs on:
+
+1.  Oasis implementation of [Microsoft Azure](https://azure.microsoft.com/en-gb/resources/cloud-computing-dictionary/what-is-azure/).
+2.  How to implement [Kubernetes](https://kubernetes.io/docs/concepts/overview/).
+3.  How to deploy and manage the Oasis platform on a [Kubernetes](https://kubernetes.io/docs/concepts/overview/) cluster.
+
+# Oasis API v1 schema
+
+A full json schema for the available options in the v1 API file can be found here:
+
+https://github.com/OasisLMF/OasisPlatform/releases/download/1.28.0/openapi-schema-1.28.0.json
+
+This is useful for more technical users who are looking to create their own UI or integrate Oasis with an existing system. The v1 schema hierarchy is shown in `json` format in right column of the page. An interactive version of the schema, with descriptions and examples, can be found below:
+
+***NOTE:***
+***This link may not be the most up to date version of the schema. Please check what the latest version of OasisPlatform is, and amend the link accordingly.***

redoc/v2/description.md

@@ -0,0 +1,66 @@
+# Introduction 
+
+Oasis has a full REST API for managing exposure data and operating
+modelling workflows. API Swagger documentation can be found
+[here](http://api.oasislmfdev.org/swagger/). An evaluation version of
+the Oasis platform and using can be deployed using the [Oasis evaluation
+repository](https://github.com/OasisLMF/OasisEvaluation). This includes
+a Jupyter notebook that illustrates the basic operation of the API,
+using the Python API client.
+
+# Oasis API
+
+The Oasis Platform release now includes a full API for operating
+catastrophe models and a general consolidation of the platform
+architecture. Windows SQL server is no longer a strict requirement. The
+platform can be run via docker containers on a single machine or, if
+required, scaled up to run on a cluster.
+
+Docker support is the main requirement for running the platform. A Linux
+based installation is the main focus of this example deployment. Running
+the install script from this repository automates install process of the
+**OasisPlatform API v1**, User Interface and example PiWind model.
+
+The **Oasis API** is the components of the Oasis platform that manages
+all the elements of the plaform that are required to build, run, and
+test models. The diagram below shows how the **Oasis API** sits behind
+the `Oasis-UI`{.interpreted-text role="doc"}, that you use to operate
+your catastrophe models.
+
+*Oasis docker componets*:
+
+<img src="https://raw.githubusercontent.com/OasisLMF/GenerateDocs/feature/update_docs/src/images/oasis_containers.png" alt="Oasis docker componets" style="align-center; width:600px;"/>
+
+
+# API deployment in the Oasis Enterprise Platform
+
+The **Oasis Enterprise Platform** is supported by the **OasisPlatform API v2**, and is an open source
+[Kubernetes](https://kubernetes.io/docs/concepts/overview/) based, cloud
+computing cluster, which is deployable in [Microsoft Azure](https://azure.microsoft.com/en-gb/resources/cloud-computing-dictionary/what-is-azure/) via 
+[Helm charts](https://helm.sh/docs/topics/charts/) and [Bicep scripts](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deployment-script-bicep)
+to setup the Azure cloud services. The diagram below sets out the
+
+**Oasis Enterprise Platform** architecture:
+
+<img src="https://raw.githubusercontent.com/OasisLMF/GenerateDocs/feature/update_docs/src/images/diag_oasis_components.png" alt="Oasis Enterprise Platform Architecture" style="align-center; width:600px;"/>
+
+# Links for further information
+
+There is more information availible in the [Oasis GitHub](https://github.com/OasisLMF).
+
+This includes detailed walkthorughs on:
+
+1.  Oasis implementation of [Microsoft Azure](https://azure.microsoft.com/en-gb/resources/cloud-computing-dictionary/what-is-azure/).
+2.  How to implement [Kubernetes](https://kubernetes.io/docs/concepts/overview/).
+3.  How to deploy and manage the Oasis platform on a [Kubernetes](https://kubernetes.io/docs/concepts/overview/) cluster.
+
+# Oasis API v2 schema
+
+A full json schema for the available options in the v2 API file can be found here:
+
+https://github.com/OasisLMF/OasisPlatform/releases/download/2.2.0/openapi-schema-2.2.0.json
+
+This is useful for more technical users who are looking to create their own UI or integrate Oasis with an existing system. The v2 schema hierarchy is shown in `json` format in right column of the page. An interactive version of the schema, with descriptions and examples, can be found below:
+
+***NOTE:***
+***This link may not be the most up to date version of the schema. Please check what the latest version of OasisPlatform is, and amend the link accordingly.***

requirements.txt

@@ -15,3 +15,7 @@ docutils
 furo
 sphinxcontrib-youtube
 virtualenv
+sphinx-jsonschema==1.19.1
+requests
+ods-tools
+sphinxcontrib-redoc