CTOOLS-276: update READMEs

finbourne · Aug 5, 2024 · 1d5ba75 · 1d5ba75
1 parent b7ab58c
commit 1d5ba75
Show file tree

Hide file tree

Showing 23 changed files with 317 additions and 310 deletions.
diff --git a/generate/config-template.json b/generate/config-template.json
@@ -8,6 +8,7 @@
     "licenseInfo": "MIT",
     "datetimeFormat": "%Y-%m-%dT%H:%M:%S.%fZ",
     "isLusidPackage": true,
+    "application": "${APPLICATION_NAME}",
     "gitUserId": "${GIT_USER_ID}",
     "gitRepoId": "${GIT_REPO_ID}",
     "additionalProperties": {

diff --git a/generate/default_templates/api_doc.mustache b/generate/default_templates/api_doc.mustache
@@ -0,0 +1,74 @@
+# {{packageName}}.{{classname}}{{#description}}
+{{.}}{{/description}}
+
+All URIs are relative to *{{basePath}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+# **{{{operationId}}}**
+> {{#returnType}}{{{.}}} {{/returnType}}{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{/required}}{{^required}}{{{paramName}}}={{{paramName}}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
+
+{{{summary}}}{{#notes}}
+
+{{{.}}}{{/notes}}
+
+### Example
+
+{{#hasAuthMethods}}
+{{#authMethods}}
+{{#isBasic}}
+{{#isBasicBasic}}
+* Basic Authentication ({{name}}):
+{{/isBasicBasic}}
+{{#isBasicBearer}}
+* Bearer{{#bearerFormat}} ({{{.}}}){{/bearerFormat}} Authentication ({{name}}):
+{{/isBasicBearer}}
+{{/isBasic}}
+{{#isApiKey}}
+* Api Key Authentication ({{name}}):
+{{/isApiKey }}
+{{#isOAuth}}
+* OAuth Authentication ({{name}}):
+{{/isOAuth }}
+{{/authMethods}}
+{{/hasAuthMethods}}
+{{> api_doc_example }}
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
+{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{baseType}}.md){{/isPrimitiveType}}{{/isFile}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{.}}]{{/defaultValue}}
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
+
+### Authorization
+
+{{^authMethods}}No authorization required{{/authMethods}}{{#authMethods}}[{{{name}}}](../README.md#{{{name}}}){{^-last}}, {{/-last}}{{/authMethods}}
+
+### HTTP request headers
+
+ - **Content-Type**: {{#consumes}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+ - **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+{{#responses.0}}
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+{{#responses}}
+**{{code}}** | {{message}} | {{#headers}} * {{baseName}} - {{description}} <br> {{/headers}}{{^headers.0}} - {{/headers.0}} |
+{{/responses}}
+{{/responses.0}}
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
+{{/operation}}
+{{/operations}}
diff --git a/generate/split-readme.sh b/generate/split-readme.sh
@@ -0,0 +1,16 @@
+#!/bin/bash
+
+set -eETuo pipefail
+
+failure() {
+  local lineno="$1"
+  local msg="$2"
+  echo "Failed at $lineno: $msg"
+}
+trap 'failure ${LINENO} "$BASH_COMMAND"' ERR
+
+# split the README into two, and move one up a level
+split_line=$(grep -n START_OF_NESTED_README generate/.output/sdk/README.md | cut -d: -f1)
+head -n $(( split_line - 1 )) generate/.output/sdk/README.md > generate/.output/README.md
+tail -n +$(( split_line + 1 )) generate/.output/sdk/README.md > generate/.output/sdk/README.md.new
+mv generate/.output/sdk/README.md.new generate/.output/sdk/README.md
diff --git a/generate/templates/README.mustache b/generate/templates/README.mustache
@@ -1,94 +1,94 @@
-# {{{projectName}}}
-{{#appDescriptionWithNewLines}}
-{{{.}}}
-{{/appDescriptionWithNewLines}}
+![LUSID_by_Finbourne](./resources/Finbourne_Logo_Teal.svg)
 
-This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
+# Python SDK for the {{appName}}
+
+## Contents
+
+- [Summary](#summary)
+- [Versions](#versions)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+    * [Environment variables](#environment-variables)
+    * [Secrets file](#secrets-file)
+    * [Example](#example)
+- [Endpoints and models](#endpoints-and-models)
+
+## Summary
+
+This is the python SDK for the {{appName}}, part of the [LUSID by FINBOURNE](https://www.finbourne.com/lusid-technology) platform. To use it you'll need a LUSID account - [sign up for free at lusid.com](https://www.lusid.com/app/signup).
+
+{{> description }}
+
+For more details on other applications in the LUSID platform, see [Understanding all the applications in the LUSID platform](https://support.lusid.com/knowledgebase/article/KA-01787).
+
+This sdk supports `Production`, `Early Access`, `Beta` and `Experimental` API endpoints. For more details on API endpoint categories, see [What is the LUSID feature release lifecycle](https://support.lusid.com/knowledgebase/article/KA-01786). To find out which category an API endpoint falls into, see the [swagger page](https://{{host}}{{basePathWithoutHost}}/swagger/index.html).
+
+This code is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project.
+
+## Versions
 
 - API version: {{appVersion}}
-- Package version: {{packageVersion}}
-{{^hideGenerationTimestamp}}
-- Build date: {{generatedDate}}
-{{/hideGenerationTimestamp}}
-- Build package: {{generatorClass}}
-{{#infoUrl}}
-For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
-{{/infoUrl}}
+- SDK version: {{packageVersion}}
 
-## Requirements.
+## Requirements
 
-Python {{{generatorLanguageVersion}}}
+- Python {{{generatorLanguageVersion}}}
 
-## Installation & Usage
-### pip install
+## Installation
 
-If the python package is hosted on a repository, you can install directly using:
+If using [poetry](https://python-poetry.org/docs/)
 
-```sh
-pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git
 ```
-(you may need to run `pip` with root permission: `sudo pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git`)
-
-Then import the package:
-```python
-import {{{packageName}}}
+poetry add {{{projectName}}}
 ```
 
-### Setuptools
-
-Install via [Setuptools](http://pypi.python.org/pypi/setuptools).
+If using [pip](https://pypi.org/project/pip/)
 
-```sh
-python setup.py install --user
 ```
-(or `sudo python setup.py install` to install the package for all users)
+pip install {{{projectName}}}
+```
 
-Then import the package:
+Then import the package in your python file
 ```python
 import {{{packageName}}}
 ```
 
-### Tests
-
-Execute `pytest` to run the tests.
-
 ## Getting Started
 
-You'll need to provide some configuration to connect to the {{packageName}} application.
-These can be provided using a secrets file or environment variables.
+You'll need to provide some configuration to connect to the {{appName}} - see the articles about [short-lived access tokens](https://support.lusid.com/knowledgebase/article/KA-01654) and a [long-lived Personal Access Token](https://support.lusid.com/knowledgebase/article/KA-01774). This configuration can be provided using a secrets file or environment variables. 
 
 ### Environment variables
 
-In order to use [short lived access tokens](https://support.lusid.com/knowledgebase/article/KA-01654/en-us) you will need to have appropriate values set for the following environment variables:
-
+Required for a short-lived access token
 ``` 
-FBN_TOKEN_URL,
-{{#lambda.uppercase}}FBN_{{packageName}}_API_URL{{/lambda.uppercase}},
-FBN_USERNAME,
-FBN_PASSWORD,
-FBN_CLIENT_ID,
+FBN_TOKEN_URL
+FBN_{{#lambda.uppercase}}{{#lambda.snakecase}}{{application}}{{/lambda.snakecase}}{{/lambda.uppercase}}_URL
+FBN_USERNAME
+FBN_PASSWORD
+FBN_CLIENT_ID
 FBN_CLIENT_SECRET
 ```
 
-To use a long lived Personal Access Token, you must provide the following environment variables:
+Required for a long-lived access token
 ``` 
-{{#lambda.uppercase}}FBN_{{packageName}}_API_URL{{/lambda.uppercase}},
+FBN_{{#lambda.uppercase}}{{#lambda.snakecase}}{{application}}{{/lambda.snakecase}}{{/lambda.uppercase}}_URL
 FBN_ACCESS_TOKEN
 ```
 
-You can send your requests to {{packageName}} via a proxy, by setting `FBN_PROXY_ADDRESS`. 
-If your proxy has basic auth enabled, you must akso supply `FBN_PROXY_USERNAME` and `FBN_PROXY_PASSWORD`
+You can send your requests to the {{appName}} via a proxy, by setting `FBN_PROXY_ADDRESS`. If your proxy has basic auth enabled, you must also set `FBN_PROXY_USERNAME` and `FBN_PROXY_PASSWORD`.
 
 ### Secrets file
 
-In order to use [short lived access tokens](https://support.lusid.com/knowledgebase/article/KA-01654/en-us) you will need to have appropriate values set in a `secrets.json` file in the same folder as your script.
+The secrets file must be in the current working directory.
 
-``` 
+Required for a short-lived access token
+```json
 {
     "api":
     {
         "tokenUrl":"<your-token-url>",
-        "{{packageName}}Url":"<FINBOURNE-application-url>",
+        "{{#lambda.camelcase}}{{application}}{{/lambda.camelcase}}Url":"https://<your-domain>.lusid.com{{basePathWithoutHost}}",
         "username":"<your-username>",
         "password":"<your-password>",
         "clientId":"<your-client-id>",
@@ -97,25 +97,24 @@ In order to use [short lived access tokens](https://support.lusid.com/knowledgeb
 }
 ```
 
-To use a long lived Personal Access Token, you must provide a `secrets.json` with the following variables:
-``` 
+Required for a long-lived access token
+```json
 {
     "api":
     {
-        "{{packageName}}Url":"<FINBOURNE-application-url>",
+        "{{#lambda.camelcase}}{{application}}{{/lambda.camelcase}}Url":"https://<your-domain>.lusid.com{{basePathWithoutHost}}",
         "accessToken":"<your-access-token>"
     }
 }
 ```
 
-You can send your requests to {{packageName}} via a proxy, by adding a proxy section to your `secrets.json`. 
-If your proxy has basic auth enabled, you must also supply a `username` and `password` in this section.
+You can send your requests to the {{appName}} via a proxy, by adding a proxy section. If your proxy has basic auth enabled, you must also supply a `username` and `password` in this section.
 
-``` 
+```json
 {
     "api":
     {
-        "{{packageName}}Url":"<FINBOURNE-application-url>",
+        "{{#lambda.camelcase}}{{application}}{{/lambda.camelcase}}Url":"https://<your-domain>.lusid.com{{basePathWithoutHost}}",
         "accessToken":"<your-access-token>"
     },
     "proxy":
@@ -127,8 +126,33 @@ If your proxy has basic auth enabled, you must also supply a `username` and `pas
 }
 ```
 
-### Using the SDK
+{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}### Example
+{{> example}}
+{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
+
+## Endpoints and models
+
+- See [Documentation for API Endpoints](sdk/README.md#documentation-for-api-endpoints) for a description of each endpoint
+- See [Documentation for Models](sdk/README.md#documentation-for-models) for descriptions of the models used
+
+START_OF_NESTED_README
+<a id="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *{{{basePath}}}*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{{summary}}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
 
-Please follow the [installation procedure](#installation--usage) and then run the following:
+<a id="documentation-for-models"></a>
+## Documentation for Models
 
-{{> common_README }}
+{{#modelPackage}}
+{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
+{{/model}}{{/models}}
+{{/modelPackage}}
+{{^modelPackage}}
+No model defined in this package
+{{/modelPackage}}
diff --git a/generate/templates/api_doc.mustache b/generate/templates/api_doc.mustache
@@ -0,0 +1,52 @@
+# {{packageName}}.{{classname}}{{#description}}
+{{.}}{{/description}}
+
+All URIs are relative to *{{basePath}}*
+
+Method | HTTP request | Description
+------------- | ------------- | -------------
+{{#operations}}{{#operation}}[**{{operationId}}**]({{classname}}.md#{{operationId}}) | **{{httpMethod}}** {{path}} | {{summary}}
+{{/operation}}{{/operations}}
+
+{{#operations}}
+{{#operation}}
+# **{{{operationId}}}**
+> {{#returnType}}{{{.}}} {{/returnType}}{{{operationId}}}({{#allParams}}{{#required}}{{{paramName}}}{{/required}}{{^required}}{{{paramName}}}={{{paramName}}}{{/required}}{{^-last}}, {{/-last}}{{/allParams}})
+
+{{{summary}}}{{#notes}}
+
+{{{.}}}{{/notes}}
+
+### Example
+
+{{> example}}
+
+### Parameters
+{{^allParams}}This endpoint does not need any parameter.{{/allParams}}{{#allParams}}{{#-last}}
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------{{/-last}}{{/allParams}}
+{{#allParams}} **{{paramName}}** | {{#isFile}}**{{dataType}}**{{/isFile}}{{^isFile}}{{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{baseType}}.md){{/isPrimitiveType}}{{/isFile}}| {{description}} | {{^required}}[optional] {{/required}}{{#defaultValue}}[default to {{.}}]{{/defaultValue}}
+{{/allParams}}
+
+### Return type
+
+{{#returnType}}{{#returnTypeIsPrimitive}}**{{{returnType}}}**{{/returnTypeIsPrimitive}}{{^returnTypeIsPrimitive}}[**{{{returnType}}}**]({{returnBaseType}}.md){{/returnTypeIsPrimitive}}{{/returnType}}{{^returnType}}void (empty response body){{/returnType}}
+
+### HTTP request headers
+
+ - **Content-Type**: {{#consumes}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/consumes}}{{^consumes}}Not defined{{/consumes}}
+ - **Accept**: {{#produces}}{{{mediaType}}}{{^-last}}, {{/-last}}{{/produces}}{{^produces}}Not defined{{/produces}}
+
+{{#responses.0}}
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+{{#responses}}
+**{{code}}** | {{message}} | {{#headers}} * {{baseName}} - {{description}} <br> {{/headers}}{{^headers.0}} - {{/headers.0}} |
+{{/responses}}
+{{/responses.0}}
+
+[Back to top](#) &#8226; [Back to API list](../README.md#documentation-for-api-endpoints) &#8226; [Back to Model list](../README.md#documentation-for-models) &#8226; [Back to README](../README.md)
+
+{{/operation}}
+{{/operations}}