diff options
| author |   Gregory Glover <gg2147@att.com> | 2017-10-10 12:18:00 +0000 |
|---|---|---|
| committer |   Gerrit Code Review <gerrit@onap.org> | 2017-10-10 12:18:00 +0000 |
| commit | 1f6cac44fa61db99bc530ca6513bfdccf3cc23e5 (patch) | |
| tree | aee05acd1b05789f1a34498a988d931eb53a5658 /docs/templates/sections | |
| parent | f07646fc4b449d2e0fb14303c48f50b9e0c7d8e1 (diff) | |
| parent | 7134cba7aa509a5ee7628244c52979e02807d252 (diff) | |
Merge "Improve templates and add references in guides"
Diffstat (limited to 'docs/templates/sections')
| -rw-r--r-- | docs/templates/sections/adminstration.rst | 24 | ||||
| -rw-r--r-- | docs/templates/sections/apiexample/dcaecdap.rst | 757 | ||||
| -rw-r--r-- | docs/templates/sections/apiexample/httpdomain.rst | 10 | ||||
| -rw-r--r-- | docs/templates/sections/apiexample/swagger2markup.rst | 24 | ||||
| -rw-r--r-- | docs/templates/sections/apiexample/swaggerv2doc.rst | 11 | ||||
| -rw-r--r-- | docs/templates/sections/apiexample/vfcexample.rst | 768 | ||||
| -rw-r--r-- | docs/templates/sections/apiexample/worddoc2rst.rst | 11 | ||||
| -rw-r--r-- | docs/templates/sections/architecture.rst | 27 | ||||
| -rw-r--r-- | docs/templates/sections/build.rst | 23 | ||||
| -rw-r--r-- | docs/templates/sections/configuration.rst | 27 | ||||
| -rw-r--r-- | docs/templates/sections/consumedapis.rst | 16 | ||||
| -rw-r--r-- | docs/templates/sections/delivery.rst | 44 | ||||
| -rw-r--r-- | docs/templates/sections/design.rst | 13 | ||||
| -rw-r--r-- | docs/templates/sections/humaninsterfaces.rst | 17 | ||||
| -rw-r--r-- | docs/templates/sections/installation.rst | 20 | ||||
| -rw-r--r-- | docs/templates/sections/logging.rst | 22 | ||||
| -rw-r--r-- | docs/templates/sections/offeredapis.rst | 26 | ||||
| -rw-r--r-- | docs/templates/sections/release-notes.rst | 46 |
18 files changed, 1886 insertions, 0 deletions
diff --git a/docs/templates/sections/adminstration.rst b/docs/templates/sections/adminstration.rst new file mode 100644 index 000000000..94a740718 --- /dev/null +++ b/docs/templates/sections/adminstration.rst @@ -0,0 +1,24 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Administration +============== + + +.. note:: + * This section is used to describe a software component from the perspective of on-going + operation including regular processes and actions that are taken to configure and manage + the component. + + * This section is typically: provided for platform-component or applications; and + referenced in user guides + + * This note must be removed after content has been added. + + +Processes +--------- + + +Actions +------- diff --git a/docs/templates/sections/apiexample/dcaecdap.rst b/docs/templates/sections/apiexample/dcaecdap.rst new file mode 100644 index 000000000..bc7f7bf35 --- /dev/null +++ b/docs/templates/sections/apiexample/dcaecdap.rst @@ -0,0 +1,757 @@ +=============== +CDAP Broker API +=============== + +:Date: 2017-10-09 + +.. contents:: + :depth: 3 +.. + +Overview +======== + +Version information +------------------- + +*Version* : 4.0.10 + +Paths +===== + +GET / +----- + +Description +~~~~~~~~~~~ + +shows some information about this service + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful response | `info <#_info> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ + +GET /application +---------------- + +Description +~~~~~~~~~~~ + +get all applications registered with this broker + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful response | < | +| | | `appname <#_ap | +| | | pname>`__ | +| | | > array | ++---------+----------------------------------------------------+----------------+ + +PUT /application\*/{appname} +---------------------------- + +Description +~~~~~~~~~~~ + +(This is a hacky way of supporting "oneOf" because Swagger does not +support oneOf https://github.com/OAI/OpenAPI-Specification/issues/333. +This is the same endpoint as PUT /application/appname, except the PUT +body is different.) + +Register a hydrator app for service and configuration discovery. This +will light up a metrics and health endpoint for this app. ``appname`` is +assumed to also be the key in consul. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **putbody | required put body | `hydratorappput | +| * | ** | | <#_hydratorapppu | +| | | *required | | t>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `Application < | +| | | #_application> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ +| **400** | put was performed but the appname was already | No Content | +| | registered with the broker, or Invalid PUT body | | ++---------+----------------------------------------------------+----------------+ + +Consumes +~~~~~~~~ + +- ``application/json`` + +Produces +~~~~~~~~ + +- ``application/json`` + +POST /application/delete +------------------------ + +Description +~~~~~~~~~~~ + +endpoint to delete multiple applications at once. Returns an array of +status codes, where statuscode[i] = response returned from +DELETE(application/i) + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Body* | | **postbod | required post body | `multideleteput | +| * | y** | | <#_multideletepu | +| | | *required | | t>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful response | < | +| | | `returncode <# | +| | | _returncode>`_ | +| | | _ | +| | | > array | ++---------+----------------------------------------------------+----------------+ + +GET /application/{appname} +-------------------------- + +Description +~~~~~~~~~~~ + +Returns the representation of the application resource, including the +links for healthcheck and metrics. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `Application < | +| | | #_application> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker. | | ++---------+----------------------------------------------------+----------------+ + +PUT /application/{appname} +-------------------------- + +Description +~~~~~~~~~~~ + +Register an app for service and configuration discovery. This will light +up a metrics and health endpoint for this app. ``appname`` is assumed to +also be the key in consul. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **putbody | required put body | `appput <#_apppu | +| * | ** | | t>`__ | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `Application < | +| | | #_application> | +| | | `__ | ++---------+----------------------------------------------------+----------------+ +| **400** | put was performed but the appname was already | No Content | +| | registered with the broker, or Invalid PUT body | | ++---------+----------------------------------------------------+----------------+ + +Consumes +~~~~~~~~ + +- ``application/json`` + +Produces +~~~~~~~~ + +- ``application/json`` + +DELETE /application/{appname} +----------------------------- + +Description +~~~~~~~~~~~ + +Remove an app for service and configuration discovery. This will remove +the metrics and health endpoints for this app. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker. | | ++---------+----------------------------------------------------+----------------+ + +GET /application/{appname}/healthcheck +-------------------------------------- + +Description +~~~~~~~~~~~ + +Perform a healthcheck on the running app appname. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application to get the | string (test) | +| * | ** | healthcheck for. | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response, healthcheck pass | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker, or the healthcheck has failed (though I | | +| | would like to disambiguiate from the first case, | | +| | CDAP returns a 404 for this). | | ++---------+----------------------------------------------------+----------------+ + +GET /application/{appname}/metrics +---------------------------------- + +Description +~~~~~~~~~~~ + +Get live (real-time) app specific metrics for the running app appname. +Metrics are customized per each app by the component developer + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application to get | string (test) | +| * | ** | metrics for. | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | `MetricsObject | +| | | <#_metricsobj | +| | | ect>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | no app with name 'appname' registered with this | No Content | +| | broker. | | ++---------+----------------------------------------------------+----------------+ + +PUT /application/{appname}/reconfigure +-------------------------------------- + +Description +~~~~~~~~~~~ + +Reconfigures the application. + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **appname | Name of the application. | string (text) | +| * | ** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **putbody | required put body | `reconfigput <#_ | +| * | ** | | reconfigput>`__ | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | Successful response | No Content | ++---------+----------------------------------------------------+----------------+ +| **400** | Bad request. Can happen with 1) {appname} is not | No Content | +| | registered with the broker, 2) the required PUT | | +| | body is wrong, or 3) the smart interface was | | +| | chosen and none of the config keys match anything | | +| | in app\_config or app\_preferences | | ++---------+----------------------------------------------------+----------------+ + +Definitions +=========== + +Application +----------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **appname | application name | string | +| ** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **connect | input URL that you can POST data into (URL | string | +| ionurl** | of the CDAP stream) | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **healthc | fully qualified url to perform healthcheck | string | +| heckurl** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **metrics | fully qualified url to get metrics from | string | +| url** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **service | a list of HTTP services exposed by this | < | +| endpoints** | CDAP application | `service\_method | +| | *optional | | <#_service_meth | +| * | | od>`__ | +| | | > array | ++-------------+---------------------------------------------+------------------+ +| | **url** | fully qualified url of the resource | string | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +MetricsObject +------------- + +key,value object where the key is 'appmetrics' and the value is an app +dependent json and specified by the component developer + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **appmetrics** | object | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +appname +------- + +an application name + +*Type* : string + +appput +------ + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **app\_co | the application config JSON | object | +| nfig** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **app\_pr | the application preferences JSON | object | +| eferences** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the name of the CDAP artifact to be added | string | +| t\_name** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **cdap\_a | denotes whether this is a program-flowlet | enum | +| pplication\ | style application or a hydrator pipeline. | (program-flowlet | +| _type** | For program-flowlet style apps, this value | ) | +| | *optional | must be "program-flowlet" | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **jar\_ur | the URL that the JAR you’re deploying | string | +| l** | resides | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **namespa | the cdap namespace this is deployed into | string | +| ce** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | | < | +| \_preferenc | | `programpref <#_ | +| es** | | programpref>`__ | +| | *optional | | > array | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | | < | +| s** | | `programs <#_pro | +| | *optional | | grams>`__ | +| * | | > array | ++-------------+---------------------------------------------+------------------+ +| | **service | | < | +| s** | | `service\_endpoi | +| | *optional | | nt <#_service_en | +| * | | dpoint>`__ | +| | | > array | ++-------------+---------------------------------------------+------------------+ +| | **streamn | name of the CDAP stream to ingest data into | string | +| ame** | this app. Should come from the developer | | +| | *optional | and Tosca model. | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +hydratorappput +-------------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **cdap\_a | denotes whether this is a program-flowlet | enum | +| pplication\ | style application or a hydrator pipeline. | (hydrator-pipeli | +| _type** | For hydrator, this value must be | ne) | +| | *required | "hydrator-pipeline" | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **depende | represents a list of dependencies to be | < | +| ncies** | loaded for this pipeline. Not required. | `hydratordep <#_ | +| | *optional | | hydratordep>`__ | +| * | | > array | ++-------------+---------------------------------------------+------------------+ +| | **namespa | the cdap namespace this is deployed into | string | +| ce** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **pipelin | the URL of the config.json for this | string | +| e\_config\_ | pipeline | | +| json\_url** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **streamn | name of the CDAP stream to ingest data into | string | +| ame** | this app. Should come from the developer | | +| | *required | and Tosca model. | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +hydratordep +----------- + +represents a hydrator pipeline dependency. An equivelent to the +following CURLs are formed with the below four params shown in CAPS +"curl -v -w"\\n" -X POST +http://cdapurl:11015/v3/namespaces/setelsewhere/artifacts/ARTIFACT_NAME +-H "Artifact-Extends:ARTIFACT\_EXTENDS\_HEADER" -H +“Artifact-Version:ARTIFACT\_VERSION\_HEADER” –data-binary @(DOWNLOADED +FROM ARTIFACT\_URL)","curl -v -w"\\n" -X PUT +http://cdapurl:11015/v3/namespaces/setelsewhere/artifacts/ARTIFACT_NAME/versions/ARTIFACT_VERSION_HEADER/properties +-d (DOWNLOADED FROM UI\_PROPERTIES\_URL)" + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **artifac | the value of the header that gets passed in | string | +| t\_extends\ | for artifact-extends, e.g., | | +| _header** | "Artifact-Extends:system:cdap-data-pipeline | | +| | *required | [4.0.1,5.0.0)" | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the name of the artifact | string | +| t\_name** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the URL of the artifact JAR | string | +| t\_url** | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **artifac | the value of the header that gets passed in | string | +| t\_version\ | for artifact-version, e.g., | | +| _header** | "Artifact-Version:1.0.0-SNAPSHOT" | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **ui\_pro | the URL of the properties.json if the | string | +| perties\_ur | custom artifact has UI properties. This is | | +| l** | optional. | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +info +---- + +some broker information + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **broker | the API version of this running broker | string | +| API | | | +| version** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **cdap | The GUI port of the CDAP cluster this | integer | +| GUI | broker is managing. Mostly to help users of | | +| port** | this API check their application in cdap. | | +| | *optional | Note, will return UNKNOWN\_CDAP\_VERSION if | | +| * | it cannot be determined. | | ++-------------+---------------------------------------------+------------------+ +| | **cdap | the version of the CDAP cluster this broker | string | +| cluster | is managing. Note, will return | | +| version** | UKNOWN\_CDAP\_VERSION if it cannot be | | +| | *optional | determined. | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **managed | the url of the CDAP cluster API this broker | string | +| cdap | is managing | | +| url** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **number | | integer | +| of | | | +| applicati | | | +| ons | | | +| registere | | | +| d** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **uptime | | integer | +| (s)** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +multideleteput +-------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **appnames** | < `appname <#_appname>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +programpref +----------- + +the list of programs in this CDAP app + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **program | the name of the program | string | +| \_id** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | the preference JSON to set for this program | object | +| \_pref** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | must be one of flows, mapreduce, schedules, | string | +| \_type** | spark, workflows, workers, or services | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +programs +-------- + +the list of programs in this CDAP app + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **program | the name of the program | string | +| \_id** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **program | must be one of flows, mapreduce, schedules, | string | +| \_type** | spark, workflows, workers, or services | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +reconfigput +----------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **config* | the config JSON | object | +| * | | | +| | *required | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **reconfi | the type of reconfiguration | enum | +| guration\_t | | (program-flowlet | +| ype** | | -app-config, | +| | *required | | program-flowlet- | +| * | | app-preferences, | +| | | program-flowlet- | +| | | smart) | ++-------------+---------------------------------------------+------------------+ + +returncode +---------- + +an httpreturncode + +*Type* : integer + +service\_endpoint +----------------- + +descirbes a service endpoint, including the service name, the method +name, and the method type (GET, PUT, etc, most of the time will be GET) + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **endpoin | GET, POST, PUT, etc | string | +| t\_method** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **service | the name of the endpoint on the service | string | +| \_endpoint* | | | +| * | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **service | the name of the service | string | +| \_name** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +service\_method +--------------- + +a URL and HTTP method exposed via a CDAP service + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **method* | HTTP method you can perform on the URL, | string | +| * | e.g., GET, PUT, etc | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **url** | the fully qualified URL in CDAP for this | string | +| | *optional | service | | +| * | | | ++-------------+---------------------------------------------+------------------+ diff --git a/docs/templates/sections/apiexample/httpdomain.rst b/docs/templates/sections/apiexample/httpdomain.rst new file mode 100644 index 000000000..f06d0067a --- /dev/null +++ b/docs/templates/sections/apiexample/httpdomain.rst @@ -0,0 +1,10 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Sphinx httpdomain directive +=========================== + +.. http:get:: path + + For more information see `<https://pythonhosted.org/sphinxcontrib-httpdomain>`_ + diff --git a/docs/templates/sections/apiexample/swagger2markup.rst b/docs/templates/sections/apiexample/swagger2markup.rst new file mode 100644 index 000000000..b83bd4d96 --- /dev/null +++ b/docs/templates/sections/apiexample/swagger2markup.rst @@ -0,0 +1,24 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + +Swagger2Markup(asciidoc) to Asciidoctor(docbook) to Pandoc(RST) +=============================================================== + +vfc-nfvo-lcm +------------ + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + vfcexample.rst + + +DCAE and YAML intput +-------------------- + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + dcaecdap.rst diff --git a/docs/templates/sections/apiexample/swaggerv2doc.rst b/docs/templates/sections/apiexample/swaggerv2doc.rst new file mode 100644 index 000000000..a0f13e061 --- /dev/null +++ b/docs/templates/sections/apiexample/swaggerv2doc.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + + +Sphinx swaggerv2doc directive +----------------------------- +Here is an example of vfc-nfvo-lcm API. + +.. swaggerv2doc:: https://gerrit.onap.org/r/gitweb?p=vfc/nfvo/lcm.git;a=blob_plain;f=lcm/swagger/vfc.nslcm.swagger.json + + diff --git a/docs/templates/sections/apiexample/vfcexample.rst b/docs/templates/sections/apiexample/vfcexample.rst new file mode 100644 index 000000000..71d3b7814 --- /dev/null +++ b/docs/templates/sections/apiexample/vfcexample.rst @@ -0,0 +1,768 @@ +================================================= +ONAP VFC Network Service Lifecycle Management API +================================================= + +:Date: 2017-10-09 + +.. contents:: + :depth: 3 +.. + +Overview +======== + +VFC Network Service Lifecycle Management Rest API. + +Version information +------------------- + +*Version* : 1.0.0 + +Contact information +------------------- + +| *Contact* : ONAP VFC team +| *Contact Email* : onap-discuss@lists.onap.org + +URI scheme +---------- + +| *BasePath* : /api/nslcm/v1 +| *Schemes* : HTTP, HTTPS + +Consumes +-------- + +- ``application/json`` + +Produces +-------- + +- ``application/json`` + +Paths +===== + +jobstatus +--------- + +:: + + GET /jobs/{jobId} + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **jobId** | job Id | string | +| * | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Query | | **respons | job response message id | string | +| ** | eId** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++-------------------------+--------------------------------------------------+ +| HTTP Code | Schema | ++=========================+==================================================+ +| **202** | `JobDetailInfo <#_jobdetailinfo>`__ | ++-------------------------+--------------------------------------------------+ + +Tags +~~~~ + +- job + +ns create +--------- + +:: + + POST /ns + +Description +~~~~~~~~~~~ + +ns create + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Body* | | **NSCreat | NS Instance Create Request | `NsCreateRequest | +| * | eRequest** | | <#_nscreaterequ | +| | | *required | | est>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful operation | `NsCreateRespo | +| | | nse <#_nscreat | +| | | eresponse>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns get +------ + +:: + + GET /ns + +Description +~~~~~~~~~~~ + +ns get + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Query | | **csarId* | job response message id | string | +| ** | * | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful operation | `NsInstancesIn | +| | | fo <#_nsinstan | +| | | cesinfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns Instantiate +-------------- + +:: + + POST /ns/{nsInstanceId}/Instantiate + +Description +~~~~~~~~~~~ + +ns Instantiate + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **nsInsta | | string | +| * | nceId** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **NSInsta | NS Instantiate Request Body | `NsInstantiateRe | +| * | ntiateReque | | quest <#_nsinsta | +| | st** | | ntiaterequest>`_ | +| | | *required | | _ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **201** | Invalid Request | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns scale +-------- + +:: + + POST /ns/{nsInstanceId}/scale + +Description +~~~~~~~~~~~ + +ns scale + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **nsInsta | | string | +| * | nceId** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **ScaleNS | Scale NS Request Body | `NsScaleRequest | +| * | Request** | | <#_nsscalereques | +| | | *required | | t>`__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **201** | Invalid Request | No Content | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns get +------ + +:: + + GET /ns/{ns_instance_id} + +Description +~~~~~~~~~~~ + +ns get + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **200** | successful operation | `NsInstanceInf | +| | | o <#_nsinstanc | +| | | einfo>`__ | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns delete +--------- + +:: + + DELETE /ns/{ns_instance_id} + +Description +~~~~~~~~~~~ + +ns delete + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **ns\_ins | Identifier of the NS instance. | string | +| * | tance\_id** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **204** | The NS instance resource and the associated NS | No Content | +| | identifier were deleted successfully. | | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns heal +------- + +:: + + POST /ns/{ns_instance_id}/heal + +Description +~~~~~~~~~~~ + +ns heal + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **ns\_ins | Identifier of the NS instance. | string | +| * | tance\_id** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **healVnf | healVnfData | `NsHealRequest < | +| * | Data** | | #_nshealrequest> | +| | | *required | | `__ | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **202** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **404** | URL not found | No Content | ++---------+----------------------------------------------------+----------------+ +| **500** | the url is invalid | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +ns terminate +------------ + +:: + + POST /ns/{ns_instance_id}/terminate + +Description +~~~~~~~~~~~ + +ns terminate + +Parameters +~~~~~~~~~~ + ++---------+-------------+--------------------------------------+------------------+ +| Type | Name | Description | Schema | ++=========+=============+======================================+==================+ +| **Path* | | **ns\_ins | Identifier of the NS instance. | string | +| * | tance\_id** | | | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ +| **Body* | | **NsTermi | NsTerminateRequest | `NsTerminateRequ | +| * | nateRequest | | est <#_nstermina | +| | ** | | terequest>`__ | +| | | *required | | | +| | * | | | ++---------+-------------+--------------------------------------+------------------+ + +Responses +~~~~~~~~~ + ++---------+----------------------------------------------------+----------------+ +| HTTP | Description | Schema | +| Code | | | ++=========+====================================================+================+ +| **202** | | `JobInfo <#_jo | +| | | binfo>`__ | ++---------+----------------------------------------------------+----------------+ +| **500** | the url is invalid | No Content | ++---------+----------------------------------------------------+----------------+ + +Tags +~~~~ + +- ns + +Definitions +=========== + +JobDetailInfo +------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **jobId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **responseDescriptor** | `responseDescriptor <#_jobdetailinfo_resp | +| | *optional* | onsedescriptor>`__ | ++--------------------------------+-------------------------------------------+ + +**responseDescriptor** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **errorCode** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **progress** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **responseHistoryList** | < `jobResponseInfo <#_jobresponseinfo>`__ | +| | *optional* | > array | ++--------------------------------+-------------------------------------------+ +| | **responseId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **status** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **statusDescription** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +JobInfo +------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **jobId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +LocationConstraint +------------------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **locationConstraints** | `locationConstraints <#_locationconstrain | +| | *optional* | t_locationconstraints>`__ | ++--------------------------------+-------------------------------------------+ +| | **vnfProfileId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +**locationConstraints** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **vimid** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsCreateRequest +--------------- + ++-------------+---------------------------------------------+------------------+ +| Name | Description | Schema | ++=============+=============================================+==================+ +| | **csarId* | the NS package ID | string | +| * | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **descrip | | string | +| tion** | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ +| | **nsName* | | string | +| * | | | +| | *optional | | | +| * | | | ++-------------+---------------------------------------------+------------------+ + +NsCreateResponse +---------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **nsInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsHealRequest +------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **additionalParams** | `additionalParams <#_nshealrequest_additi | +| | *optional* | onalparams>`__ | ++--------------------------------+-------------------------------------------+ +| | **cause** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +**additionalParams** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **action** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **actionvminfo** | `actionvminfo <#_nshealrequest_actionvmin | +| | *optional* | fo>`__ | ++--------------------------------+-------------------------------------------+ + +**actionvminfo** + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **vmid** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vmname** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsInstanceInfo +-------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **description** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsState** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nsdId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vlInfo** | < `vlInfo <#_vlinfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfInfo** | < `vnfInfo <#_vnfinfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnffgInfo** | < `vnffgInfo <#_vnffginfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsInstancesInfo +--------------- + +*Type* : < `NsInstanceInfo <#_nsinstanceinfo>`__ > array + +NsInstantiateRequest +-------------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **LocationConstraints** | < | +| | *optional* | `LocationConstraint <#_locationconstraint | +| | >`__ | +| | > array | ++--------------------------------+-------------------------------------------+ +| | **additionalParamForNs** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsScaleByStepsData +------------------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **aspectId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **numberOfSteps** | integer | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **scalingDirection** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsScaleRequest +-------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **scaleNsByStepsData** | `NsScaleByStepsData <#_nsscalebystepsdata | +| | *optional* | >`__ | ++--------------------------------+-------------------------------------------+ +| | **scaleType** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +NsTerminateRequest +------------------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **gracefulTerminationTimeout | string | +| ** | | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **terminationType** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +cpInfo +------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **cpInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **cpInstanceName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **cpdId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +jobResponseInfo +--------------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **errorCode** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **progress** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **responseId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **status** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **statusDescription** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +vlInfo +------ + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **relatedCpInstanceId** | < `cpInfo <#_cpinfo>`__ > array | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vlInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vlInstanceName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vldId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +vnfInfo +------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **vnfInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfInstanceName** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfdId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ + +vnffgInfo +--------- + ++--------------------------------+-------------------------------------------+ +| Name | Schema | ++================================+===========================================+ +| | **cpId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **nfp** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **pnfId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **virtualLinkId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnfId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ +| | **vnffgInstanceId** | string | +| | *optional* | | ++--------------------------------+-------------------------------------------+ diff --git a/docs/templates/sections/apiexample/worddoc2rst.rst b/docs/templates/sections/apiexample/worddoc2rst.rst new file mode 100644 index 000000000..2e1f8148c --- /dev/null +++ b/docs/templates/sections/apiexample/worddoc2rst.rst @@ -0,0 +1,11 @@ + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Word Document Converted to RST +------------------------------ +This is an example of an APPC API Guide. + +.. toctree:: + :maxdepth: 1 + + ../../../submodules/appc.git/docs/APPC API Guide/APPC API Guide diff --git a/docs/templates/sections/architecture.rst b/docs/templates/sections/architecture.rst new file mode 100644 index 000000000..8daa0d3bc --- /dev/null +++ b/docs/templates/sections/architecture.rst @@ -0,0 +1,27 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Architecture +============ + +.. note:: + * This section is used to describe a software component from a high level + view of capability, common usage scenarios, and interactions with other + components required in the usage scenarios. + + * The architecture section is typically: provided in a platform-component + and sdk collections; and referenced from developer and user guides. + + * This note must be removed after content has been added. + + +Capabilities +------------ + + +Usage Scenarios +--------------- + + +Interactions +------------ diff --git a/docs/templates/sections/build.rst b/docs/templates/sections/build.rst new file mode 100644 index 000000000..99a061c24 --- /dev/null +++ b/docs/templates/sections/build.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Build +===== + +.. note:: + * This section is used to describe how a software component is built from source + into something ready for use either in a run-time environment or to build other + components. + + * This section is typically provided for a platform-component, application, and sdk; and + referenced in developer guides. + + * This note must be removed after content has been added. + + +Environment +----------- + + +Steps +----- diff --git a/docs/templates/sections/configuration.rst b/docs/templates/sections/configuration.rst new file mode 100644 index 000000000..085f9c667 --- /dev/null +++ b/docs/templates/sections/configuration.rst @@ -0,0 +1,27 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Configuration +============= + +.. note:: + * This section is used to describe the options a software component offers for configuration. + + * Configuration is typically: provided for platform-component and sdk projects; + and referenced in developer and user guides. + + * This note must be removed after content has been added. + + + +Example ... + +You can provide the following in ``basic.conf`` + +``host=ADDRESS`` + The address of the host + +``port=PORT`` + The port used for signaling + + Optional. Default: ``8080`` diff --git a/docs/templates/sections/consumedapis.rst b/docs/templates/sections/consumedapis.rst new file mode 100644 index 000000000..c2af4c20e --- /dev/null +++ b/docs/templates/sections/consumedapis.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Consumed APIs +============= + +.. note:: + * This section is used to reference APIs that a software component depends on + and uses from other sources. + + * Consumed APIs should be a specific link to the offered APIs from another component + or external source. + + * This note must be removed after content has been added. + + diff --git a/docs/templates/sections/delivery.rst b/docs/templates/sections/delivery.rst new file mode 100644 index 000000000..f3f083a73 --- /dev/null +++ b/docs/templates/sections/delivery.rst @@ -0,0 +1,44 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Delivery +======== + +.. note:: + * This section is used to describe a software component packaging. + For a run-time component this might be executable images, containers, etc. + For an SDK this might be libraries. + + * This section is typically provided for a platform-component and sdk; + and referenced in developer and user guides + + * This note must be removed after content has been added. + +Example use of a block diagram. + +.. blockdiag:: + + + blockdiag layers { + orientation = portrait + a -> m; + b -> n; + c -> x; + m -> y; + m -> z; + group l1 { + color = blue; + x; y; z; + } + group l2 { + color = yellow; + m; n; + } + group l3 { + color = orange; + a; b; c; + } + + } + + diff --git a/docs/templates/sections/design.rst b/docs/templates/sections/design.rst new file mode 100644 index 000000000..f173a2fb5 --- /dev/null +++ b/docs/templates/sections/design.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Design +====== + +.. note:: + * This section is used to describe the internal design structure of a software component. + + * This section is typically provided: for a platform-component and sdk; and + referenced in developer guides. + + * This note must be removed after content has been added. diff --git a/docs/templates/sections/humaninsterfaces.rst b/docs/templates/sections/humaninsterfaces.rst new file mode 100644 index 000000000..429284608 --- /dev/null +++ b/docs/templates/sections/humaninsterfaces.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Human Interfaces +================ + +.. note:: + * This section is used to describe a software component's command line and graphical + user interfaces. + + * This section is typically: provided for a platform-component and application; and + referenced from user guides. + + * This note must be removed after content has been added. + + + diff --git a/docs/templates/sections/installation.rst b/docs/templates/sections/installation.rst new file mode 100644 index 000000000..be64a63bb --- /dev/null +++ b/docs/templates/sections/installation.rst @@ -0,0 +1,20 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Installation +============ + +.. note:: + * This section is used to describe how a software component is acquired and installed. + + * This section is typically: provided for a platform-component and application; and + referenced in user guides. + + * This note must be removed after content has been added. + +Environment +----------- + + +Steps +----- diff --git a/docs/templates/sections/logging.rst b/docs/templates/sections/logging.rst new file mode 100644 index 000000000..39eabfba7 --- /dev/null +++ b/docs/templates/sections/logging.rst @@ -0,0 +1,22 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Logging +======= + +.. note:: + * This section is used to describe the informational or diagnostic messages emitted from + a software component and the methods or collecting them. + + * This section is typically: provided for a platform-component and sdk; and + referenced in developer and user guides + + * This note must be removed after content has been added. + + +Where to Access Information +--------------------------- + + +Error / Warning Messages +------------------------ diff --git a/docs/templates/sections/offeredapis.rst b/docs/templates/sections/offeredapis.rst new file mode 100644 index 000000000..b1b8f41e8 --- /dev/null +++ b/docs/templates/sections/offeredapis.rst @@ -0,0 +1,26 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Offered APIs +============ + +.. note:: + * This section is used to describe the external interfaces offered by a software component + + * This section is typically: provided for a platform-component and sdk; and + referenced in developer guides and api reference manuals. + + * This note must be removed after content has been added. + + + +Here are several examples: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + apiexample/swaggerv2doc.rst + apiexample/swagger2markup.rst + apiexample/worddoc2rst.rst + apiexample/httpdomain.rst diff --git a/docs/templates/sections/release-notes.rst b/docs/templates/sections/release-notes.rst new file mode 100644 index 000000000..ca257314e --- /dev/null +++ b/docs/templates/sections/release-notes.rst @@ -0,0 +1,46 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Release Notes +============= + +.. note:: + * This Release Notes must be updated each time the team decides to Release new artifacts. + * The scope of this Release Notes is for this particular component. In other words, each ONAP component has its Release Notes. + * This Release Notes is cumulative, the most recently Released artifact is made visible in the top of this Release Notes. + * Except the date and the version number, all the other sections are optional but there must be at least one section describing the purpose of this new release. + * This note must be removed after content has been added. + + +Version: x.y.z +-------------- + + +:Release Date: yyyy-mm-dd + + + +**New Features** + +One or two sentences explaining the purpose of this Release. + +**Bug Fixes** + - `CIMAN-65 <https://jira.onap.org/browse/CIMAN-65>`_ and a sentence explaining what this defect is addressing. +**Known Issues** + - `CIMAN-65 <https://jira.onap.org/browse/CIMAN-65>`_ and two, three sentences. + One sentences explaining what is the issue. + + Another sentence explaining the impact of the issue. + + And an optional sentence providing a workaround. + +**Security Issues** + You may want to include a reference to CVE (Common Vulnerabilities and Exposures) `CVE <https://cve.mitre.org>`_ + + +**Upgrade Notes** + +**Deprecation Notes** + +**Other** + +=========== |