From 5baea4608e685f67e9dec77cfee57cacb73662dd Mon Sep 17 00:00:00 2001 From: Rich Bennett Date: Wed, 13 Sep 2017 03:19:19 -0400 Subject: Enhancement and additions for webinar Add templates, revise master index, guides, and release document Improve project integration instructions based on 5 project integrations. Change-Id: I2a3e62737f3c126b7f5fb7cc4f53b35dba4f1d8f Issue-ID: DOC-26 Signed-off-by: Rich Bennett --- docs/templates/component-info/consumed-apis.csv | 1 - docs/templates/component-info/index.rst | 90 ---------------------- docs/templates/component-info/offered-apis.csv | 2 - docs/templates/index.rst | 14 ---- .../platform-component/administration.rst | 19 +++++ .../templates/platform-component/configuration.rst | 19 +++++ docs/templates/platform-component/consumedapis.rst | 8 ++ docs/templates/platform-component/delivery.rst | 31 ++++++++ .../platform-component/humaninterfaces.rst | 19 +++++ docs/templates/platform-component/index.rst | 19 +++++ docs/templates/platform-component/installation.rst | 14 ++++ docs/templates/platform-component/logging.rst | 14 ++++ docs/templates/platform-component/offeredapis.rst | 12 +++ docs/templates/release-notes/bug-fixes.rst | 5 ++ docs/templates/release-notes/deprecation-notes.rst | 5 ++ docs/templates/release-notes/index.rst | 15 ++++ docs/templates/release-notes/known-issues.rst | 5 ++ docs/templates/release-notes/new-features.rst | 5 ++ docs/templates/release-notes/other.rst | 5 ++ docs/templates/release-notes/security-issues.rst | 5 ++ docs/templates/release-notes/upgrade-notes.rst | 5 ++ docs/templates/sdk/build.rst | 7 ++ docs/templates/sdk/index.rst | 15 ++++ docs/templates/sdk/interfaces.rst | 3 + docs/templates/sdk/libraries.rst | 7 ++ docs/templates/sdk/logging.rst | 14 ++++ docs/templates/sdk/offeredapis.rst | 12 +++ 27 files changed, 263 insertions(+), 107 deletions(-) delete mode 100644 docs/templates/component-info/consumed-apis.csv delete mode 100644 docs/templates/component-info/index.rst delete mode 100644 docs/templates/component-info/offered-apis.csv delete mode 100644 docs/templates/index.rst create mode 100644 docs/templates/platform-component/administration.rst create mode 100644 docs/templates/platform-component/configuration.rst create mode 100644 docs/templates/platform-component/consumedapis.rst create mode 100644 docs/templates/platform-component/delivery.rst create mode 100644 docs/templates/platform-component/humaninterfaces.rst create mode 100644 docs/templates/platform-component/index.rst create mode 100644 docs/templates/platform-component/installation.rst create mode 100644 docs/templates/platform-component/logging.rst create mode 100644 docs/templates/platform-component/offeredapis.rst create mode 100644 docs/templates/release-notes/bug-fixes.rst create mode 100644 docs/templates/release-notes/deprecation-notes.rst create mode 100644 docs/templates/release-notes/index.rst create mode 100644 docs/templates/release-notes/known-issues.rst create mode 100644 docs/templates/release-notes/new-features.rst create mode 100644 docs/templates/release-notes/other.rst create mode 100644 docs/templates/release-notes/security-issues.rst create mode 100644 docs/templates/release-notes/upgrade-notes.rst create mode 100644 docs/templates/sdk/build.rst create mode 100644 docs/templates/sdk/index.rst create mode 100644 docs/templates/sdk/interfaces.rst create mode 100644 docs/templates/sdk/libraries.rst create mode 100644 docs/templates/sdk/logging.rst create mode 100644 docs/templates/sdk/offeredapis.rst (limited to 'docs/templates') diff --git a/docs/templates/component-info/consumed-apis.csv b/docs/templates/component-info/consumed-apis.csv deleted file mode 100644 index 811d1755d..000000000 --- a/docs/templates/component-info/consumed-apis.csv +++ /dev/null @@ -1 +0,0 @@ -repo.subrepo.subrepo|API Reference diff --git a/docs/templates/component-info/index.rst b/docs/templates/component-info/index.rst deleted file mode 100644 index dfcfc747e..000000000 --- a/docs/templates/component-info/index.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -Component Information Template -============================== -High level architecture, design, and packaging information for release planning and delivery. - -.. toctree:: - :maxdepth: 1 - - -Delivery --------- -Th package component is composed of the functional layers and packaged into run-time components as illustrated in the following diagrams. - -.. 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; - } - - } - - -Offered APIs ------------- - -.. csv-table:: - :header-rows: 0 - :header: "Container or Library", "API Reference", "Purpose", "Protocol", "Port", "TCP/UDP" - :widths: 20, 25, 25, 10, 10, 10 - :delim: | - :file: offered-apis.csv - - -Consumed APIs -------------- - -.. csv-table:: - :header-rows: 0 - :header: "Project Repo/Group ID", "Container or Library Offering API" - :widths: 30, 30 - :delim: | - :file: consumed-apis.csv - -Logging & Diagnostic Information --------------------------------- -Description of how to interact with and diagnose problems with the components in the run-time packaging. - - -Installation ------------- -Steps to Install - - -Configuration -------------- -Where are they provided? -What are parameters and values? - - -Administration --------------- - -How to run and manage the component. - - -Human Interfaces ----------------- -Basic info on the interface type, ports/protocols provided over, etc. - - - diff --git a/docs/templates/component-info/offered-apis.csv b/docs/templates/component-info/offered-apis.csv deleted file mode 100644 index 6300998f6..000000000 --- a/docs/templates/component-info/offered-apis.csv +++ /dev/null @@ -1,2 +0,0 @@ -XXX Container|API Reference link|Create or Delete XYZ|xxx|9999|TCP -YYY Library|API Reference link|Create or Delete XYZ|xxxx|xxxx|xxxx diff --git a/docs/templates/index.rst b/docs/templates/index.rst deleted file mode 100644 index 0f920a4a3..000000000 --- a/docs/templates/index.rst +++ /dev/null @@ -1,14 +0,0 @@ - -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _templates: - -Templates -========= - -.. toctree:: - :maxdepth: 1 - :glob: - - **/index - diff --git a/docs/templates/platform-component/administration.rst b/docs/templates/platform-component/administration.rst new file mode 100644 index 000000000..1d512cf02 --- /dev/null +++ b/docs/templates/platform-component/administration.rst @@ -0,0 +1,19 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Administration +-------------- +Describe expected changes and the processes and actions taken for each. + + +Processes ++++++++++ +* Process 1 +* Process 2 + +Actions ++++++++ +* Action X +* Action Y + diff --git a/docs/templates/platform-component/configuration.rst b/docs/templates/platform-component/configuration.rst new file mode 100644 index 000000000..c0c969f85 --- /dev/null +++ b/docs/templates/platform-component/configuration.rst @@ -0,0 +1,19 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Configuration +------------- +Describe configurations how to provide parameters and value + +Basic Setup ++++++++++++ + +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/platform-component/consumedapis.rst b/docs/templates/platform-component/consumedapis.rst new file mode 100644 index 000000000..c4309cdb1 --- /dev/null +++ b/docs/templates/platform-component/consumedapis.rst @@ -0,0 +1,8 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Consumed APIs +============= +References to APIs offered by other components + + diff --git a/docs/templates/platform-component/delivery.rst b/docs/templates/platform-component/delivery.rst new file mode 100644 index 000000000..cfcab0449 --- /dev/null +++ b/docs/templates/platform-component/delivery.rst @@ -0,0 +1,31 @@ +Delivery +-------- +Describe how functions are packaged into run-time components. +For some components a block diagram may be useful. + +.. 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/platform-component/humaninterfaces.rst b/docs/templates/platform-component/humaninterfaces.rst new file mode 100644 index 000000000..03cc875ed --- /dev/null +++ b/docs/templates/platform-component/humaninterfaces.rst @@ -0,0 +1,19 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Human Interfaces +---------------- +Provide info on the targeted user, interface types, ports/protocols to access, etc. + +Target Users +++++++++++++ + +Interface Type +++++++++++++++ + +Access +++++++ + + + + diff --git a/docs/templates/platform-component/index.rst b/docs/templates/platform-component/index.rst new file mode 100644 index 000000000..4364739ee --- /dev/null +++ b/docs/templates/platform-component/index.rst @@ -0,0 +1,19 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Platform Component +================== +Provide an overview of the ONAP Platform component capabilities here. +Add or remove sections below as appropriate for the platform component. + +.. toctree:: + :maxdepth: 2 + + delivery.rst + offeredapis.rst + consumedapis.rst + logging.rst + installation.rst + configuration.rst + administration.rst + humaninterfaces.rst diff --git a/docs/templates/platform-component/installation.rst b/docs/templates/platform-component/installation.rst new file mode 100644 index 000000000..3238236c4 --- /dev/null +++ b/docs/templates/platform-component/installation.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Installation +------------ +Describe the environment and steps to install. + + +Environment ++++++++++++ + + +Steps ++++++ diff --git a/docs/templates/platform-component/logging.rst b/docs/templates/platform-component/logging.rst new file mode 100644 index 000000000..8d480e283 --- /dev/null +++ b/docs/templates/platform-component/logging.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Logging & Diagnostic Information +-------------------------------- +Description of how to interact with and diagnose problems with the components +as delivered. + +Where to Access Information ++++++++++++++++++++++++++++ + + +Error / Warning Messages +++++++++++++++++++++++++ diff --git a/docs/templates/platform-component/offeredapis.rst b/docs/templates/platform-component/offeredapis.rst new file mode 100644 index 000000000..3e3b5b3d0 --- /dev/null +++ b/docs/templates/platform-component/offeredapis.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Offered APIs +============ +List APIs offered. One or more of the following examples may be appropriate. + +* java docs link +* rest API swagger json definition displayed with sphinx directive .. swaggerv2doc: +* a restructured text document + diff --git a/docs/templates/release-notes/bug-fixes.rst b/docs/templates/release-notes/bug-fixes.rst new file mode 100644 index 000000000..ee4ff9faf --- /dev/null +++ b/docs/templates/release-notes/bug-fixes.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Bug Fixes +--------- + diff --git a/docs/templates/release-notes/deprecation-notes.rst b/docs/templates/release-notes/deprecation-notes.rst new file mode 100644 index 000000000..e954e8764 --- /dev/null +++ b/docs/templates/release-notes/deprecation-notes.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Deprecation Notes +----------------- + diff --git a/docs/templates/release-notes/index.rst b/docs/templates/release-notes/index.rst new file mode 100644 index 000000000..adc76f935 --- /dev/null +++ b/docs/templates/release-notes/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Release Notes +============= + +.. toctree:: + :maxdepth: 2 + + new-features.rst + bug-fixes.rst + known-issues.rst + security-issues.rst + upgrade-notes.rst + deprecation-notes.rst + other.rst diff --git a/docs/templates/release-notes/known-issues.rst b/docs/templates/release-notes/known-issues.rst new file mode 100644 index 000000000..01c93d124 --- /dev/null +++ b/docs/templates/release-notes/known-issues.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Known Issues +------------ + diff --git a/docs/templates/release-notes/new-features.rst b/docs/templates/release-notes/new-features.rst new file mode 100644 index 000000000..ab86bb949 --- /dev/null +++ b/docs/templates/release-notes/new-features.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +New Features +------------ + diff --git a/docs/templates/release-notes/other.rst b/docs/templates/release-notes/other.rst new file mode 100644 index 000000000..2ce683b5b --- /dev/null +++ b/docs/templates/release-notes/other.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Other +----- + diff --git a/docs/templates/release-notes/security-issues.rst b/docs/templates/release-notes/security-issues.rst new file mode 100644 index 000000000..96e1fe95e --- /dev/null +++ b/docs/templates/release-notes/security-issues.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Security Issues +--------------- + diff --git a/docs/templates/release-notes/upgrade-notes.rst b/docs/templates/release-notes/upgrade-notes.rst new file mode 100644 index 000000000..f31c74a69 --- /dev/null +++ b/docs/templates/release-notes/upgrade-notes.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Upgrade Notes +------------- + diff --git a/docs/templates/sdk/build.rst b/docs/templates/sdk/build.rst new file mode 100644 index 000000000..11f4ac537 --- /dev/null +++ b/docs/templates/sdk/build.rst @@ -0,0 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Building components that use the SDK +------------------------------------ + + diff --git a/docs/templates/sdk/index.rst b/docs/templates/sdk/index.rst new file mode 100644 index 000000000..8c31c9b58 --- /dev/null +++ b/docs/templates/sdk/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Software Development Kit +======================== +Provide an overview of SDK capabilities here. + +.. toctree:: + :maxdepth: 2 + + offeredapis.rst + libraries.rst + interfaces.rst + logging.rst + build.rst diff --git a/docs/templates/sdk/interfaces.rst b/docs/templates/sdk/interfaces.rst new file mode 100644 index 000000000..d28496fa2 --- /dev/null +++ b/docs/templates/sdk/interfaces.rst @@ -0,0 +1,3 @@ +Interfaces +---------- +Language bindings diff --git a/docs/templates/sdk/libraries.rst b/docs/templates/sdk/libraries.rst new file mode 100644 index 000000000..36143660a --- /dev/null +++ b/docs/templates/sdk/libraries.rst @@ -0,0 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Libraries +--------- +Libraries provided including package/Nexus groupID names, language bindings, etc. + diff --git a/docs/templates/sdk/logging.rst b/docs/templates/sdk/logging.rst new file mode 100644 index 000000000..8d480e283 --- /dev/null +++ b/docs/templates/sdk/logging.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Logging & Diagnostic Information +-------------------------------- +Description of how to interact with and diagnose problems with the components +as delivered. + +Where to Access Information ++++++++++++++++++++++++++++ + + +Error / Warning Messages +++++++++++++++++++++++++ diff --git a/docs/templates/sdk/offeredapis.rst b/docs/templates/sdk/offeredapis.rst new file mode 100644 index 000000000..3e3b5b3d0 --- /dev/null +++ b/docs/templates/sdk/offeredapis.rst @@ -0,0 +1,12 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +Offered APIs +============ +List APIs offered. One or more of the following examples may be appropriate. + +* java docs link +* rest API swagger json definition displayed with sphinx directive .. swaggerv2doc: +* a restructured text document + -- cgit 1.2.3-korg