Merge "Template updates - sections"

15 files changed, 315 insertions, 107 deletions

diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst b/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst
index 3cde22948..e776c7ff6 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst
@@ -19,5 +19,5 @@ Platform Component
    ../sections/installation.rst
    ../sections/configuration.rst
    ../sections/administration.rst
-   ../sections/humaninterfaces.rst
+   ../sections/userinterfaces.rst
    ../sections/release-notes.rst
diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/index.rst b/docs/guides/onap-developer/how-to-use-docs/templates/index.rst
new file mode 100644
index 000000000..0ec88194a
--- /dev/null
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/index.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
+.. Copyright 2021 ONAP contributors, Nokia
+
+
+
+Templates
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   collections/sdk.rst
+   collections/platform-component.rst
+   sections/offeredapis.rst
+   sections/consumedapis.rst
+   sections/architecture.rst
+   sections/design.rst
+   sections/logging.rst
+   sections/administration.rst
+   sections/installation.rst
+   sections/delivery.rst
+   sections/userinterfaces.rst
+   sections/release-notes.rst
+   sections/build.rst
+   sections/configuration.rst
diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst
index 94a740718..841a55291 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst
@@ -1,24 +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
 ==============
 
-
-.. 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. 
-   
+     the component.
    * This section is typically: provided for platform-component or applications; and
-     referenced in user guides
-   
+     referenced in user guides.
    * This note must be removed after content has been added.
 
 
-Processes
+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 %
 
-Actions
--------
+..
+  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-developer/how-to-use-docs/templates/sections/architecture.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst
index 8daa0d3bc..d9a895a38 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst
@@ -1,5 +1,6 @@
 .. 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
 ============
@@ -7,11 +8,11 @@ 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.  
-   
+     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.
 
 
diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst
index 99a061c24..0fcf3153f 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst
@@ -1,23 +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
 =====
 
-.. 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 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.
+  * 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-developer/how-to-use-docs/templates/sections/configuration.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst
index 085f9c667..6d1ec29ba 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst
@@ -4,24 +4,59 @@
 Configuration
 =============
 
-.. note::
-   * This section is used to describe the options a software component offers for 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.
-   
-   * This note must be removed after content has been added.
 
 
+Pre-requisites
+--------------
 
-Example ...
+..
+  List here any dependencies and pre-requisites, e.g. component has to be
+  deployed, necessary connections have been established, etc.
 
-You can provide the following in ``basic.conf``
 
-``host=ADDRESS``
-  The address of the host
+Editing the configuration file
+------------------------------
 
-``port=PORT``
-  The port used for signaling
+..
+  Describe the parameters and their values included in the config file.
 
-  Optional. Default: ``8080``
+
+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-developer/how-to-use-docs/templates/sections/consumedapis.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst
index c2af4c20e..3a0cd6ad1 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst
@@ -1,16 +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
 =============
 
-.. 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.
-
+     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-developer/how-to-use-docs/templates/sections/delivery.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst
index f3f083a73..32f8450cc 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst
@@ -1,44 +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
 ========
 
-.. 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 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
-   
-   * This note must be removed after content has been added.
+     and referenced in developer and user guides.
 
-Example use of a block diagram.
+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 {
-	color = blue;
-	x; y; z;
-	}
-   group l2 {
-	color = yellow;
-	m; n; 
-	}
-   group l3 {
-	color = orange;
-	a; b; c;
-	}
-
-   }
 
 
+    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-developer/how-to-use-docs/templates/sections/design.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst
index f173a2fb5..66c5f3651 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst
@@ -1,13 +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
 ======
 
-.. note::
-   * This section is used to describe the internal design structure of a software component.
+..
+   * 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.
+
+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-developer/how-to-use-docs/templates/sections/humaninterfaces.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/humaninterfaces.rst
deleted file mode 100644
index 429284608..000000000
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/humaninterfaces.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-.. 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/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst
index be64a63bb..deac057b1 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst
@@ -1,20 +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
 ============
 
-.. 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 section is used to describe how a software component is delivered and
+   installed.
 
-   * This note must be removed after content has been added.
+   * 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
++++++++++++++++++++++++++++
 
-Steps
------
+..
+  Include both generic troubleshooting steps and ones specific to the upgrade
+  steps.
diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst
index 39eabfba7..5662acb1f 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst
@@ -5,12 +5,12 @@ Logging
 =======
 
 .. note::
-   * This section is used to describe the informational or diagnostic messages emitted from 
+   * 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.
 
 
diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst
index 23504c1da..fbb454a94 100644
--- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst
+++ b/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst
@@ -1,14 +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
 ============
 
-.. 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 
+
+   * 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.
 
+   * Include links to the generated JSON, HTML, and PDF versions.
diff --git a/docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst
new file mode 100644
index 000000000..0f6a6cb38
--- /dev/null
+++ b/docs/guides/onap-developer/how-to-use-docs/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.
diff --git a/docs/guides/onap-developer/index.rst b/docs/guides/onap-developer/index.rst
index 0d2418ba5..e7bc4998f 100644
--- a/docs/guides/onap-developer/index.rst
+++ b/docs/guides/onap-developer/index.rst
@@ -15,3 +15,9 @@ understand or contribute to the ONAP open source.
    how-to-use-docs/index
    apiref/index
 
+
+.. toctree::
+  :maxdepth: 1
+  :hidden:
+
+  how-to-use-docs/templates/index