diff options
| author |   Lusheng Ji <lji@research.att.com> | 2017-10-10 18:12:22 +0000 |
|---|---|---|
| committer | Lusheng Ji <lji@research.att.com> | 2017-10-10 18:12:34 +0000 |
| commit | 72c4fbaceb680b3b34e177ccca11efe18de599f5 (patch) | |
| tree | fefdb90f97f0e8d43772d77ea48f6f98a7c4945b | |
| parent | c8d7ad73740989d2aa5d5cab41dcc7e0c960f0fa (diff) | |
Draft docs
Issue-Id: DCAEGEN2-109
Change-Id: I85513ed5b34c0f60b8b0924b2016bbb3224beb9c
Signed-off-by: Lusheng Ji <lji@research.att.com>
| -rw-r--r-- | docs/index.rst | 25 | ||||
| -rw-r--r-- | docs/sections/adminstration.rst | 24 | ||||
| -rw-r--r-- | docs/sections/apiexample/dcaecdap.rst | 757 | ||||
| -rw-r--r-- | docs/sections/apiexample/httpdomain.rst | 10 | ||||
| -rw-r--r-- | docs/sections/apiexample/swagger2markup.rst | 24 | ||||
| -rw-r--r-- | docs/sections/apiexample/swaggerv2doc.rst | 11 | ||||
| -rw-r--r-- | docs/sections/apiexample/vfcexample.rst | 768 | ||||
| -rw-r--r-- | docs/sections/apiexample/worddoc2rst.rst | 11 | ||||
| -rw-r--r-- | docs/sections/architecture.rst | 27 | ||||
| -rw-r--r-- | docs/sections/build.rst | 23 | ||||
| -rw-r--r-- | docs/sections/configuration.rst | 27 | ||||
| -rw-r--r-- | docs/sections/consumedapis.rst | 16 | ||||
| -rw-r--r-- | docs/sections/delivery.rst | 44 | ||||
| -rw-r--r-- | docs/sections/design.rst | 13 | ||||
| -rw-r--r-- | docs/sections/humaninsterfaces.rst | 17 | ||||
| -rw-r--r-- | docs/sections/installation.rst | 20 | ||||
| -rw-r--r-- | docs/sections/logging.rst | 22 | ||||
| -rw-r--r-- | docs/sections/offeredapis.rst | 26 | ||||
| -rw-r--r-- | docs/sections/release-notes.rst | 46 |
19 files changed, 1905 insertions, 6 deletions
diff --git a/docs/index.rst b/docs/index.rst index 36dd11f2..128a7ee5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,13 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 -Data Collection Analytics and Events ------------------------------------------------- +Data Collection, Analytics, and Events (DCAE) +======================= + +.. Add or remove sections below as appropriate for the platform component. Data Collection Analytics and Events (DCAE) is the data collection and analysis subsystem of ONAP. -Its functions include collection of FCAPs data from the network entotiess (VNFs, PNFs, etc), normalization and transportation of +Its functions include collection of FCAPs data from the network entotiess (VNFs, PNFs, etc), normalization and transportation of data, analysis of data, and generations of ONAP events which can be received by other ONAP components such as Policy for subsequent operations. @@ -13,7 +16,7 @@ DCAE consists of DCAE Platform components and DCAE Services components. - DCAE Platform - Core Platform - Cloudify Manager - - Consul + - Consul - Extended Platform - Docker Host for containerized platform components - CDAP Analytics Platform for CDAP analytics applications @@ -28,9 +31,19 @@ DCAE consists of DCAE Platform components and DCAE Services components. - Holmes correlation analytics, dockerized - Threshold Crosssing Analytics (TCA), CDAP analytics application - - .. toctree:: :maxdepth: 1 + ./sections/architecture.rst + ./sections/offeredapis.rst + ./sections/consumedapis.rst + ./sections/delivery.rst + ./sections/logging.rst + ./sections/installation.rst + ./sections/configuration.rst + ./sections/administration.rst + ./sections/humaninterfaces.rst + ./sections/release-notes.rst + offeredapis.rst + diff --git a/docs/sections/adminstration.rst b/docs/sections/adminstration.rst new file mode 100644 index 00000000..94a74071 --- /dev/null +++ b/docs/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/sections/apiexample/dcaecdap.rst b/docs/sections/apiexample/dcaecdap.rst new file mode 100644 index 00000000..bc7f7bf3 --- /dev/null +++ b/docs/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/sections/apiexample/httpdomain.rst b/docs/sections/apiexample/httpdomain.rst new file mode 100644 index 00000000..f06d0067 --- /dev/null +++ b/docs/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/sections/apiexample/swagger2markup.rst b/docs/sections/apiexample/swagger2markup.rst new file mode 100644 index 00000000..b83bd4d9 --- /dev/null +++ b/docs/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/sections/apiexample/swaggerv2doc.rst b/docs/sections/apiexample/swaggerv2doc.rst new file mode 100644 index 00000000..a0f13e06 --- /dev/null +++ b/docs/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/sections/apiexample/vfcexample.rst b/docs/sections/apiexample/vfcexample.rst new file mode 100644 index 00000000..71d3b781 --- /dev/null +++ b/docs/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/sections/apiexample/worddoc2rst.rst b/docs/sections/apiexample/worddoc2rst.rst new file mode 100644 index 00000000..2e1f8148 --- /dev/null +++ b/docs/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/sections/architecture.rst b/docs/sections/architecture.rst new file mode 100644 index 00000000..8daa0d3b --- /dev/null +++ b/docs/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/sections/build.rst b/docs/sections/build.rst new file mode 100644 index 00000000..99a061c2 --- /dev/null +++ b/docs/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/sections/configuration.rst b/docs/sections/configuration.rst new file mode 100644 index 00000000..085f9c66 --- /dev/null +++ b/docs/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/sections/consumedapis.rst b/docs/sections/consumedapis.rst new file mode 100644 index 00000000..c2af4c20 --- /dev/null +++ b/docs/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/sections/delivery.rst b/docs/sections/delivery.rst new file mode 100644 index 00000000..f3f083a7 --- /dev/null +++ b/docs/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/sections/design.rst b/docs/sections/design.rst new file mode 100644 index 00000000..f173a2fb --- /dev/null +++ b/docs/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/sections/humaninsterfaces.rst b/docs/sections/humaninsterfaces.rst new file mode 100644 index 00000000..42928460 --- /dev/null +++ b/docs/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/sections/installation.rst b/docs/sections/installation.rst new file mode 100644 index 00000000..be64a63b --- /dev/null +++ b/docs/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/sections/logging.rst b/docs/sections/logging.rst new file mode 100644 index 00000000..39eabfba --- /dev/null +++ b/docs/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/sections/offeredapis.rst b/docs/sections/offeredapis.rst new file mode 100644 index 00000000..b1b8f41e --- /dev/null +++ b/docs/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/sections/release-notes.rst b/docs/sections/release-notes.rst new file mode 100644 index 00000000..ca257314 --- /dev/null +++ b/docs/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** + +=========== |