diff options
author | 2017-09-13 11:56:39 +0000 | |
---|---|---|
committer | 2017-09-13 11:56:39 +0000 | |
commit | f9d77f166ddb7beb9719684f45f244da266630ca (patch) | |
tree | a9daeeb476668310ececce2a479fa9055ea4dca3 /docs | |
parent | 81e8bf5491ace00c2ecbf337ceacd1b4e88e7916 (diff) | |
parent | 5baea4608e685f67e9dec77cfee57cacb73662dd (diff) |
Merge "Enhancement and additions for webinar"
Diffstat (limited to 'docs')
48 files changed, 489 insertions, 246 deletions
diff --git a/docs/guide/onap-developer/index.rst b/docs/guide/onap-developer/index.rst deleted file mode 100644 index a6a5d2223..000000000 --- a/docs/guide/onap-developer/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _onap_developer_guide: - -ONAP Developer Guide -==================== - -.. toctree:: - :maxdepth: 1 - - how-to-use-docs/index diff --git a/docs/guide/service-designer/index.rst b/docs/guide/service-designer/index.rst deleted file mode 100644 index b87254460..000000000 --- a/docs/guide/service-designer/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - -.. _administrator_guide: - -Admistrator Guide -================= - -.. toctree:: - :maxdepth: 2 - -More to be added ----------------- diff --git a/docs/guides/onap-developer/architecture/index.rst b/docs/guides/onap-developer/architecture/index.rst new file mode 100644 index 000000000..8d06c4f1f --- /dev/null +++ b/docs/guides/onap-developer/architecture/index.rst @@ -0,0 +1,14 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Architecture +============ + +Platform Components +------------------- + +SDKs +---- + +Dependencies +------------ + diff --git a/docs/guides/onap-developer/developing/index.rst b/docs/guides/onap-developer/developing/index.rst new file mode 100644 index 000000000..1006b2b69 --- /dev/null +++ b/docs/guides/onap-developer/developing/index.rst @@ -0,0 +1,11 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Developing ONAP +=============== + +Platform Component References +----------------------------- + +Test & Validation Requirements +------------------------------ + diff --git a/docs/guide/onap-developer/how-to-use-docs/addendum.rst b/docs/guides/onap-developer/how-to-use-docs/addendum.rst index 24cd1c7c8..160b18fde 100644 --- a/docs/guide/onap-developer/how-to-use-docs/addendum.rst +++ b/docs/guides/onap-developer/how-to-use-docs/addendum.rst @@ -26,7 +26,7 @@ Source Files ------------ Document source files have to be written in reStructuredText format (rst). -Each file would be build as an html page. +Each file would be built as an html page. Here is an example source rst file : @@ -59,6 +59,7 @@ You can add html content that only appears in html output by using the .. only:: html This line will be shown only in html version. + .. index:: single: indices Creating Indices @@ -104,6 +105,7 @@ you created in the source RST. These are simple cases with simple options. For more information about indexing with Sphinx, please see the `official Sphinx documentation <http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index>`_. + Jenkins Jobs ------------ @@ -112,8 +114,11 @@ Verify Job The verify job name is **doc-{stream}-verify-rtd** -Proposed changes in doc or any other repository that has been added as a -git submodule will be verified by this job prior to a gerrit code review. +Proposed changes in files in any repository with the path +.. bash + docs/**/*.rst + +will be verified by this job prior to a gerrit code review. Please check the Jenkins log carefully for warnings. You can improve your document even if the verify job succeeded. @@ -122,7 +127,7 @@ Merge Job The merge job name is **doc-{stream}-merge-rtd**. -When a committer merges a patch, Jenkins will automatically trigger building of -the new documentation. This might take about 15 minutes while readthedocs -builds the documentation. The newly built documentation shall show up -as appropriate placed in docs.onap.org/{branch}/path-to-file. +When a committer merges a patch that includes files matching the path described above, +the doc project merge job will trigger an update at readthedocs. +This might take about 15 minutes while readthedocs +builds the documentation. diff --git a/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst b/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst index 96b5c82ad..5321a18df 100644 --- a/docs/guide/onap-developer/how-to-use-docs/converting-formats.rst +++ b/docs/guides/onap-developer/how-to-use-docs/converting-formats.rst @@ -1,3 +1,7 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _converting-to-rst: + Converting to RST ================= diff --git a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst b/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst index 316e0af31..9586b4b5a 100644 --- a/docs/guide/onap-developer/how-to-use-docs/documentation-guide.rst +++ b/docs/guides/onap-developer/how-to-use-docs/documentation-guide.rst @@ -4,12 +4,12 @@ Introduction ============ This guide describes how to create documentation for the Open Network -Automation Platform (ONAP). ONAP projects create a variety of document -types depending on the nature of the project. Some projects will create -detailed technical descriptions such as configuration parameters or how -to use or extend the functionality of platform component. -These descriptions may be used together as a reference for that project -and/or be used in documents tailored to a specific user audience and +Automation Platform (ONAP). ONAP projects create a variety of +content depending on the nature of the project. For example projects delivering +a platform component may have different types of content than +a project that creates libraries for a software development kit. +The content from each project may be used together as a reference for that project +and/or be used in documents are tailored to a specific user audience and task they are performing. Much of the content in this document is derived from similar @@ -50,11 +50,12 @@ style, grammar, and consistency. Plain-text formatting syntaxes, such as reStructuredText, Markdown, and Textile, are a good choice for documentation because: - a. They are editor agnostic - b. The source is nearly as easy to read as the rendered text - c. Documentation can be treated exactly as source code is (e.g. versioned, -diff'ed, associated with commit messages that can be included in rendered docs) - d. Shallow learning curve + +a. They are editor agnostic +b. The source is nearly as easy to read as the rendered text +c. Documentation can be treated exactly as source code is (e.g. versioned, + diff'ed, associated with commit messages that can be included in rendered docs) +d. Shallow learning curve The documentation team chose reStructuredText largely because of Sphinx, a Python-based documentation build system, which uses reStructuredText natively. In a code base @@ -91,12 +92,12 @@ as possible because: Structure --------- -A top level master_document structure is used to organize all -documents for an ONAP release that reside in the doc git repository. +A top level master document structure is used to organize all +documents for an ONAP release and this resides in the gerrit doc repository. Complete documents or guides may reside here and reference parts of source for documentation from other project repositories A starting structure is shown below and may change as content is -intergrated for each release. Others ONAP projects will provide +integrated for each release. Other ONAP projects will provide content that is referenced from this structure. .. index:: master @@ -105,28 +106,22 @@ content that is referenced from this structure. :: docs/ - ├── release - │ ├── overview + ├── releases + │ ├── major releases + │ ├── projects + │ ├── cryptographic signatures + │ └── references + ├── onap-developer │ ├── architecture - │ ├── use-cases │ ├── tutorials - │ └── release-notes - ├── onap-developer - │ ├── design - │ ├── develop - │ ├── document - │ └── test - ├── adminstrator - │ ├── configure - │ ├── deploy - │ └── operate - ├── service-designer - │ ├── deploy - │ ├── design - │ └── portal - └── vnf-provider - ├── guidelines - └── sdk + │ ├── setting up + │ ├── developing + │ └── documenting + └── onap-users + ├── vf provider + ├── service designer + ├── service administrator + └── platform administrator @@ -135,12 +130,12 @@ Source Files All documentation for a project should be structured and stored in or below `<your_project_repo>/docs/` directory as Restructured Text. ONAP jenkins jobs that verify and merge documentation are triggered by -file changes in the docs directory and below. +RST file changes in the top level docs directory and below. .. index:: licensing -Licencing +Licensing --------- All contributions to the ONAP project are done in accordance with the ONAP licensing requirements. Documentation in ONAP is contributed @@ -156,20 +151,3 @@ files: These lines will not be rendered in the html and pdf files. - - -Templates ---------- -To encourage consistency of information across components, some -templates are available as a starting point under `doc/docs/templates/` -and listed below. With the "show source" feature on html pages, you -may be able to use portions of an existing page as starting point for -creating new content. - - -.. toctree:: - :maxdepth: 1 - :glob: - - ../../../templates/**/index - diff --git a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst index f41268f99..789ad7552 100644 --- a/docs/guide/onap-developer/how-to-use-docs/include-documentation.rst +++ b/docs/guides/onap-developer/how-to-use-docs/include-documentation.rst @@ -55,7 +55,7 @@ Setup project repositories(s) ----------------------------- These steps are performed for each project repository that provides documentation. -First let's set two variables that will be used in the following examples. +First let's set two variables that will be used in the subsequent steps. Set reponame to the project repository you are setting up just as it appears in the **Project Name** column of the Gerrit projects page. Set lfid to your Linux Foundation identity that you use to login to gerrit or for git @@ -68,6 +68,12 @@ clone requests over ssh. The next step is to add a directory in the doc project where your project will be included as a submodule and at least one reference from the doc project to the documentation index in your repository. +The following sequence will do this over ssh. + +.. caution:: + + If your access network restricts ssh, you will need to use equivalent git commands and + HTTP Passwords as described `here <http://wiki.onap.org/x/X4AP>`_. .. code-block:: bash @@ -84,9 +90,23 @@ submodule and at least one reference from the doc project to the documentation i git commit -s git review +.. caution:: + Wait for the above change to be merged before any merge to the + project repository that you have just added as a submodule. + If the project repository added as submodule changes before the doc project merge, git may not + automatically update the submodule reference on changes and/or the verify job will + fail in the step below. The last step is to create a docs directory in your repository with an index.rst file. +The following sequence will complete the minimum required over ssh. As you have time +to convert or add new content you can update the index and add files under the docs folder. + +.. hint:: + If you have additional content, you can include it by editing the + index.rst file and/or adding other files before the git commit. + See `Templates and Examples`_ below and :ref:`converting-to-rst` for more information. + .. code-block:: bash @@ -110,10 +130,11 @@ The last step is to create a docs directory in your repository with an index.rst The diagram below illustrates what is accomplished in the setup steps above from the perspective of a file structure created for a local test, a jenkins verify job, and/or published release documentation including: - - - all ONAP gerrit project repositories, - - the doc project repository master document index.rst, templates, configuration - - the submodules directory where other project repositories and directories/files may be referenced + - ONAP gerrit project repositories, + - doc project repository master document index.rst, templates, configuration, and other documents + - submodules directory where other project repositories and directories/files are referenced + - file structure: directories (ellipses), files(boxes) + - references: directory/files (solid edges), git submodule (dotted edges), sphinx toctree (dashed edges) .. graphviz:: @@ -177,10 +198,39 @@ a jenkins verify job, and/or published release documentation including: Creating Restructured Text ========================== -TODO Add simple example and references here +Templates and Examples +---------------------- +Some templates are available that capture the kinds of information +useful for different types of projects and provide simple examples of +restructured text. +You can: browse the templates below; show source to look at the Restructured +Text and Sphinx directives used; and then copy the source either from a browser window +or by downloading the file in raw form from +the `gerrit doc repository <https://gerrit.onap.org/r/gitweb?p=doc.git;a=tree;f=docs/templates;/>`_. + +.. toctree:: + :maxdepth: 1 + :glob: + + ../../../templates/**/index + +In addition to these simple templates and examples +there are many open source projects (e.g. Open Daylight, Open Stack) +that are using Sphinx and Readthedocs where you may find examples to start with. +Working with project teams we will continue to enhance templates here and +capture frequently asked questions on the developer wiki question +topic `documentation <https://wiki.onap.org/questions/topics/16384055/documentation>`_. + +Each project should: decide what is relevant content; determine the +best way to create/maintain it in a CI/CD process; and work with the +documentation team to reference content from the master index and guides. +Consider options including filling in a template, +identifying existing content that can be used as is or +easily converted, and use of Sphinx directives/extensions to automatically +generate restructured text from other source you already have. Links and References -==================== +-------------------- It's pretty common to want to reference another location in the ONAP documentation and it's pretty easy to do with reStructuredText. This is a quick primer, more information is in the diff --git a/docs/guide/onap-developer/how-to-use-docs/index.rst b/docs/guides/onap-developer/how-to-use-docs/index.rst index cd387df51..cd387df51 100644 --- a/docs/guide/onap-developer/how-to-use-docs/index.rst +++ b/docs/guides/onap-developer/how-to-use-docs/index.rst diff --git a/docs/guide/onap-developer/how-to-use-docs/style-guide.rst b/docs/guides/onap-developer/how-to-use-docs/style-guide.rst index 5d477a99b..5d477a99b 100644 --- a/docs/guide/onap-developer/how-to-use-docs/style-guide.rst +++ b/docs/guides/onap-developer/how-to-use-docs/style-guide.rst diff --git a/docs/guides/onap-developer/index.rst b/docs/guides/onap-developer/index.rst new file mode 100644 index 000000000..4787f52ec --- /dev/null +++ b/docs/guides/onap-developer/index.rst @@ -0,0 +1,17 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +.. _onap_developer_guides: + +ONAP Developer +============== +Describe the kinds of references, tutorials, specifications provided for developers. + +.. toctree:: + :maxdepth: 2 + + architecture/index + tutorials/index + settingup/index + developing/index + how-to-use-docs/index + diff --git a/docs/guides/onap-developer/settingup/index.rst b/docs/guides/onap-developer/settingup/index.rst new file mode 100644 index 000000000..112dc9669 --- /dev/null +++ b/docs/guides/onap-developer/settingup/index.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Setting Up ONAP +=============== + diff --git a/docs/templates/index.rst b/docs/guides/onap-developer/tutorials/index.rst index 0f920a4a3..5864e4d8c 100644 --- a/docs/templates/index.rst +++ b/docs/guides/onap-developer/tutorials/index.rst @@ -1,14 +1,7 @@ - .. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _templates: - -Templates +Tutorials ========= -.. toctree:: - :maxdepth: 1 - :glob: - **/index diff --git a/docs/guides/onap-user/index.rst b/docs/guides/onap-user/index.rst new file mode 100644 index 000000000..5fa4c8bca --- /dev/null +++ b/docs/guides/onap-user/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + +ONAP User +========== +Describe the different user audiences, tasks performed, and the guides provided for each. + +.. toctree:: + :maxdepth: 1 + + vnfprovider.rst + servicedesigner.rst + serviceadmin.rst + platformadmin.rst + diff --git a/docs/guide/platform-administrator/index.rst b/docs/guides/onap-user/platformadmin.rst index 7215c72be..fceea7744 100644 --- a/docs/guide/platform-administrator/index.rst +++ b/docs/guides/onap-user/platformadmin.rst @@ -1,12 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _service_designer_guide: - -Service Designer Guide +Platform Administrator ====================== -.. toctree:: - :maxdepth: 2 -More to be added ----------------- diff --git a/docs/guides/onap-user/serviceadmin.rst b/docs/guides/onap-user/serviceadmin.rst new file mode 100644 index 000000000..b2faf8613 --- /dev/null +++ b/docs/guides/onap-user/serviceadmin.rst @@ -0,0 +1,6 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Service Administrator +===================== + + diff --git a/docs/guides/onap-user/servicedesigner.rst b/docs/guides/onap-user/servicedesigner.rst new file mode 100644 index 000000000..1b51acb35 --- /dev/null +++ b/docs/guides/onap-user/servicedesigner.rst @@ -0,0 +1,5 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + +Service Designer +================ + diff --git a/docs/guide/vnf-provider/index.rst b/docs/guides/onap-user/vnfprovider.rst index c43c5f394..d64367770 100644 --- a/docs/guide/vnf-provider/index.rst +++ b/docs/guides/onap-user/vnfprovider.rst @@ -1,6 +1,5 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. _vnf_provider_guide: VNF Provider Guide ================== @@ -8,5 +7,5 @@ VNF Provider Guide .. toctree:: :maxdepth: 2 - ../../submodules/vnfrqts/guidelines.git/docs/index.rst - ../../submodules/vnfrqts/requirements.git/docs/index.rst + ../../../submodules/vnfrqts/guidelines.git/docs/index.rst + ../../../submodules/vnfrqts/requirements.git/docs/index.rst diff --git a/docs/index.rst b/docs/index.rst index ca298c119..4d7eda002 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,13 +6,11 @@ ONAP Documentation ================== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - release/index - guide/onap-developer/index - guide/service-designer/index - guide/platform-administrator/index - guide/vnf-provider/index + releases/index + guides/onap-developer/index + guides/onap-user/index diff --git a/docs/release/index.rst b/docs/release/index.rst deleted file mode 100644 index 03ffc1f33..000000000 --- a/docs/release/index.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. - - -Release -======= - -Overview of use cases, installation, release notes, etc. - - -Architecture ------------- - - -Use Cases ---------- - - -Tutorials ---------- - - - -Release Notes -------------- - -Projects Providing Documentation --------------------------------- - -.. toctree:: - :maxdepth: 1 - - repolist.rst - - - - diff --git a/docs/releases/index.rst b/docs/releases/index.rst new file mode 100644 index 000000000..eabde3a24 --- /dev/null +++ b/docs/releases/index.rst @@ -0,0 +1,32 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. + + +Releases +======== +ONAP is developed and released around 6 month cycles. After an initial major release, additional +stable point releases may be created. + +Major Releases +-------------- + +.. csv-table:: + :align: left + :header-rows: 0 + :header: "Release", "Status", "Initial Release Date", "Next Phase", "EOL Date" + :widths: 15, 10, 10, 15, 10 + + "Amsterdam", "Under Development", "TBD", "", "" + "R1.0.0 Seed Code", "EOL", "2017-04-XX", "", "" + + +.. include:: repolist.rst + + +Cryptographic Signatures +------------------------ + + +References +---------- + + diff --git a/docs/release/repolist.rst b/docs/releases/repolist.rst index 4b10d4144..a00a959d9 100644 --- a/docs/release/repolist.rst +++ b/docs/releases/repolist.rst @@ -1,13 +1,19 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. +Projects +-------- +Documentation organized by the project delivering them. +.. note:: + When available these references should be changed to release artifacts + .. toctree:: :maxdepth: 1 :titlesonly: appc <../submodules/appc.git/docs/index> + appc/deployment <../submodules/appc/deployment.git/docs/index> + clamp <../submodules/clamp.git/docs/index> + cli <../submodules/cli.git/docs/index> vnfrqts/guidelines <../submodules/vnfrqts/guidelines.git/docs/index> vnfrqts/requirements <../submodules/vnfrqts/requirements.git/docs/index> - cli <../submodules/cli.git/docs/index> - clamp <../submodules/clamp.git/docs/index> - appc/deployment <../submodules/appc/deployment.git/docs/index> 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/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 + |