diff options
Diffstat (limited to 'docs/guides/onap-documentation/templates')
15 files changed, 608 insertions, 0 deletions
diff --git a/docs/guides/onap-documentation/templates/collections/platform-component.rst b/docs/guides/onap-documentation/templates/collections/platform-component.rst new file mode 100644 index 000000000..e776c7ff6 --- /dev/null +++ b/docs/guides/onap-documentation/templates/collections/platform-component.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 + + +Platform Component +================== + +.. Add or remove sections below as appropriate for the platform component. + +.. toctree:: + :maxdepth: 1 + + ../sections/architecture.rst + ../sections/offeredapis.rst + ../sections/consumedapis.rst + ../sections/delivery.rst + ../sections/design.rst + ../sections/logging.rst + ../sections/installation.rst + ../sections/configuration.rst + ../sections/administration.rst + ../sections/userinterfaces.rst + ../sections/release-notes.rst diff --git a/docs/guides/onap-documentation/templates/collections/sdk.rst b/docs/guides/onap-documentation/templates/collections/sdk.rst new file mode 100644 index 000000000..83fbbe2ee --- /dev/null +++ b/docs/guides/onap-documentation/templates/collections/sdk.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 + +SDK +=== + +.. Add or remove sections below as appropriate for the SDK + +.. toctree:: + :maxdepth: 1 + + ../sections/architecture.rst + ../sections/offeredapis.rst + ../sections/delivery.rst + ../sections/logging.rst + ../sections/build.rst + ../sections/release-notes.rst diff --git a/docs/guides/onap-documentation/templates/index.rst b/docs/guides/onap-documentation/templates/index.rst new file mode 100644 index 000000000..c42483e51 --- /dev/null +++ b/docs/guides/onap-documentation/templates/index.rst @@ -0,0 +1,18 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2021 ONAP Contributors, Nokia + +.. _templates: + +Templates +========= + +This section provides documentation templates for the ONAP projects. We have +gathered a typical set of documents for a SDK and a Platform Component. But +feel free to add or remove templates based on your requirements. + +.. toctree:: + :maxdepth: 2 + + collections/sdk.rst + collections/platform-component.rst diff --git a/docs/guides/onap-documentation/templates/sections/administration.rst b/docs/guides/onap-documentation/templates/sections/administration.rst new file mode 100644 index 000000000..841a55291 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/administration.rst @@ -0,0 +1,69 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2021 ONAP contributors, Nokia + +Administration +============== + +.. + * 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. + + +Procedure +--------- + +.. + Use this section for each procedure you want to include. + + +Purpose +~~~~~~~ + +.. + The purpose of the procedure, what is the intended outcome, possible + dependencies. + + +Pre-requisites +~~~~~~~~~~~~~~ + +.. + Any tasks to be performed before starting the procedures, checklists, + software requirements, required users and roles, etc. + Optional section. + +You can link to `other resources <https://example.com/>`_. + + +Steps +~~~~~ + +.. + Copy the following step as many times as you need. + + +#. This is the first step of the procedure. + +.. note:: + You can add a note with additional information needed to perform the step. + +You can include commands to be executed, for example: + +.. code-block:: bash + + sudo apt-get install git -y + +You can add an image, for example, a screenshot of the GUI: + +.. figure:: https://www.onap.org/wp-content/uploads/sites/20/2017/02/logo_onap_2017.png + :alt: Example image + :width: 50 % + +.. + Add the result of the step or procedure at the end of the chapter. + If there are verification steps, add them, as well. diff --git a/docs/guides/onap-documentation/templates/sections/architecture.rst b/docs/guides/onap-documentation/templates/sections/architecture.rst new file mode 100644 index 000000000..d9a895a38 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/architecture.rst @@ -0,0 +1,28 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2021 ONAP contributors, Nokia + +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/guides/onap-documentation/templates/sections/build.rst b/docs/guides/onap-documentation/templates/sections/build.rst new file mode 100644 index 000000000..0fcf3153f --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/build.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 +.. Copyright 2021 ONAP contributors, Nokia + +Build +===== + +.. + * 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. + + +Environment +----------- + +.. + List the tools that need to be installed for building the component. + +Steps +----- + +.. + List the command(s) that need to be executed for the build. diff --git a/docs/guides/onap-documentation/templates/sections/configuration.rst b/docs/guides/onap-documentation/templates/sections/configuration.rst new file mode 100644 index 000000000..6d1ec29ba --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/configuration.rst @@ -0,0 +1,62 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Configuration +============= + +.. + * 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. + + +Pre-requisites +-------------- + +.. + List here any dependencies and pre-requisites, e.g. component has to be + deployed, necessary connections have been established, etc. + + +Editing the configuration file +------------------------------ + +.. + Describe the parameters and their values included in the config file. + + +Configuration steps +------------------- + +.. + Add the necessary steps to configure the component, including all options/ + alternatives. + Provide examples (screenshots for GUI, commands for CLI) wherever possible. + +#. Add the configuration. + +Example command: + +.. code-block:: bash + + example command <parameter> + +Example screenshot: + +.. figure:: https://www.onap.org/wp-content/uploads/sites/20/2017/02/logo_onap_2017.png + :alt: Example image + :width: 50 % + +#. Validate the configuration. + +.. code-block:: bash + + example command to validate the configuration + +Output for successful execution: + +.. code-block:: bash + + Example output diff --git a/docs/guides/onap-documentation/templates/sections/consumedapis.rst b/docs/guides/onap-documentation/templates/sections/consumedapis.rst new file mode 100644 index 000000000..3a0cd6ad1 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/consumedapis.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 +.. Copyright 2021 ONAP contributors, Nokia + +Consumed APIs +============= + +.. + * 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. diff --git a/docs/guides/onap-documentation/templates/sections/delivery.rst b/docs/guides/onap-documentation/templates/sections/delivery.rst new file mode 100644 index 000000000..32f8450cc --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/delivery.rst @@ -0,0 +1,53 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2021 ONAP contributors, Nokia + +Delivery +======== + +.. + * This section is used to describe the delivery of a software component. + 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. + +Process +------- +.. + If needed, describe the steps of the delivery pictured on the block diagram. + +.. blockdiag:: + + + blockdiag layers { + orientation = portrait + a -> m; + b -> n; + c -> x; + m -> y; + m -> z; + group l1 { + shape = line; + color = "#07819B"; + x; y; z; + } + group l2 { + shape = line; + color = "#1a3d6f"; + m; n; + } + group l3 { + shape = line; + color = "#5dbeba"; + a; b; c; + } + + } + +Deliverables +------------ + +.. + List the deliverables in the package here. diff --git a/docs/guides/onap-documentation/templates/sections/design.rst b/docs/guides/onap-documentation/templates/sections/design.rst new file mode 100644 index 000000000..66c5f3651 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/design.rst @@ -0,0 +1,32 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2021 ONAP contributors, Nokia + +Design +====== + +.. + * 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. + + +Design principles +----------------- + +.. + List the basic principles of the component and best practices, as well. + +Static design +------------- + +.. + Description of classes, objects, etc. + +Dynamic view +------------ + +.. + Communication/interaction of objects when implementing the use cases. diff --git a/docs/guides/onap-documentation/templates/sections/installation.rst b/docs/guides/onap-documentation/templates/sections/installation.rst new file mode 100644 index 000000000..deac057b1 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/installation.rst @@ -0,0 +1,73 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2021 ONAP contributors, Nokia + +Installation +============ + +.. + * This section is used to describe how a software component is delivered and + installed. + + * This section is typically: provided for a platform-component and + application; and referenced in user guides. + +Preparations +------------ + +.. + e.g. The software must be delivered as described in section Delivery. + +Environment +----------- + +.. + Cloud containers, public cloud, image formats, resource needs. + +Installation +------------ + +Procedure ++++++++++ + +#. Start the installation. + +.. + Include screenshots or specific commands as examples wherever possible. + Add the expected result, as well. + +#. Verify the installation. + +Troubleshooting the installation +++++++++++++++++++++++++++++++++ + +.. + Include both generic troubleshooting steps and ones specific to the + installation steps. + +Upgrade +------- + +.. + If there are any dependencies, mention them here. + Check compatibility between API versions. + +Procedure ++++++++++ + +#. (optional) Backup your data before starting the upgrade. + +.. + Either list the backup steps here or refer to a backup and restore guide (if + it exists). + +#. Start the upgrade. + +#. Verify the success of the upgrade. + +Troubleshooting the upgrade ++++++++++++++++++++++++++++ + +.. + Include both generic troubleshooting steps and ones specific to the upgrade + steps. diff --git a/docs/guides/onap-documentation/templates/sections/logging.rst b/docs/guides/onap-documentation/templates/sections/logging.rst new file mode 100644 index 000000000..5662acb1f --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/logging.rst @@ -0,0 +1,22 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Logging +======= + +.. note:: + * This section is used to describe the informational or diagnostic messages emitted from + a software component and the methods or collecting them. + + * This section is typically: provided for a platform-component and sdk; and + referenced in developer and user guides + + * This note must be removed after content has been added. + + +Where to Access Information +--------------------------- + + +Error / Warning Messages +------------------------ diff --git a/docs/guides/onap-documentation/templates/sections/offeredapis.rst b/docs/guides/onap-documentation/templates/sections/offeredapis.rst new file mode 100644 index 000000000..fbb454a94 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/offeredapis.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 +.. Copyright 2021 ONAP contributors, Nokia + +Offered APIs +============ + +.. + * 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. + + * Include links to the generated JSON, HTML, and PDF versions. diff --git a/docs/guides/onap-documentation/templates/sections/release-notes.rst b/docs/guides/onap-documentation/templates/sections/release-notes.rst new file mode 100644 index 000000000..11f38fed9 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/release-notes.rst @@ -0,0 +1,127 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 + International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) ONAP Project and its contributors +.. _release_notes: + +*********************** +<project> Release Notes +*********************** + +.. note:: + * The release note needs to be updated for each ONAP release + * Except the section "Release data" all other sections are optional and should be + applied where applicable + * Only the current release is to be documented in this document + * This note needs to be removed before publishing the final result + +Abstract +======== + +This document provides the release notes for the ``<releasename>`` release. + +Summary +======= + +<Give a high level description of your project with regards to this +specific release> + + +Release Data +============ + ++--------------------------------------+--------------------------------------+ +| **Project** | <project name> | +| | | ++--------------------------------------+--------------------------------------+ +| **Docker images** | make sure you include all docker | +| | images including the | +| | release version | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | <release name followed by version> | +| | | ++--------------------------------------+--------------------------------------+ + + +New features +------------ + +<Describe new features or other new additions> + +**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 to three sentences + explaining what this issue is. + +Deliverables +------------ + +Software Deliverables +~~~~~~~~~~~~~~~~~~~~~ + + +Documentation Deliverables +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Known Limitations, Issues and Workarounds +========================================= + +System Limitations +------------------ + +Any known system limitations. + + +Known Vulnerabilities +--------------------- + +Results of know vulnerabilities analysis in used modules. + + +Workarounds +----------- + +Any known workarounds. + + +Security Notes +-------------- + +**Fixed Security Issues** + +List of security issues fixed in this release including CVEs and OJSI +tickets. + +**Known Security Issues** + +List of new security issues that are left unfixed in this release including +CVEs and OJSI tickets. + + +Test Results +============ +List or refer to any project specific results + + +References +========== + +For more information on the ONAP ``<release name>`` release, please see: + +#. `ONAP Home Page`_ +#. `ONAP Documentation`_ +#. `ONAP Release Downloads`_ +#. `ONAP Wiki Page`_ + + +.. _`ONAP Home Page`: https://www.onap.org +.. _`ONAP Wiki Page`: https://wiki.onap.org +.. _`ONAP Documentation`: https://docs.onap.org +.. _`ONAP Release Downloads`: https://git.onap.org diff --git a/docs/guides/onap-documentation/templates/sections/userinterfaces.rst b/docs/guides/onap-documentation/templates/sections/userinterfaces.rst new file mode 100644 index 000000000..0f6a6cb38 --- /dev/null +++ b/docs/guides/onap-documentation/templates/sections/userinterfaces.rst @@ -0,0 +1,30 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2021 ONAP contributors, Nokia + +User Interfaces +================ + +.. + * 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. + +Graphical user interface (GUI) +------------------------------ + +.. + * Describe how to access the GUI, including user roles/credentials, browser + requirements, etc. + * Describe how to access and use the basic functionalities related to the + given component. Include screenshots wherever possible. + +Command Line Interface (CLI) +---------------------------- + +.. + * Describe how to access the CLI, including user roles/credentials. + * Include the CLI reference here, with descriptions and examples of commands + and parameters. |