Template updates - sections

Instructions and examples added, notes commented out, review comments implemented
Add example.com in the linkcheck_ignore

Issue-ID: DOC-696

Change-Id: I8221ba6f2adce534ced7d8c06fbc7f23eef39efe
Signed-off-by: Andrea Visnyei <andrea.visnyei@nokia.com>

diff --git a/docs/conf.py b/docs/conf.py
index 2de736e..3025d0e 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -5,10 +5,6 @@ branch = 'latest'
 doc_url = 'https://docs.onap.org/projects'
 master_doc = 'index'
 
-linkcheck_ignore = [
-    'http://localhost',
-]
-
 intersphinx_mapping = {}
 
 intersphinx_mapping['onap-oom-offline-installer'] = (
@@ -95,6 +91,8 @@ intersphinx_mapping['onap-aaf-authz'] = ('{}/onap-aaf-authz/en/%s'.format(doc_ur
 
 
 linkcheck_ignore = [
+    'http://localhost',
+    'https://example.com',
     'about:config',
     # this URL is not directly reachable and must be configured in the system hosts file.
     'https://portal.api.simpledemo.onap.org:30225/ONAPPORTAL/login.htm',

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 3cde229..e776c7f 100644 (file)
--- 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 (file)
index 0000000..0ec8819
--- /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 94a7407..841a552 100644 (file)
--- 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 8daa0d3..d9a895a 100644 (file)
--- 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 99a061c..0fcf315 100644 (file)
--- 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 085f9c6..6d1ec29 100644 (file)
--- 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 c2af4c2..3a0cd6a 100644 (file)
--- 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 f3f083a..32f8450 100644 (file)
--- 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 f173a2f..66c5f36 100644 (file)
--- 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 (file)
index 4292846..0000000
--- 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 be64a63..deac057 100644 (file)
--- 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 39eabfb..5662acb 100644 (file)
--- 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 23504c1..fbb454a 100644 (file)
--- 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 (file)
index 0000000..0f6a6cb
--- /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 0d2418b..e7bc499 100644 (file)
--- 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

diff --git a/tox.ini b/tox.ini
index 5807a81..4bc8f3d 100644 (file)
--- a/tox.ini
+++ b/tox.ini
@@ -14,6 +14,15 @@ whitelist_externals =
     git
     sh
 
+[testenv:docs-templates]
+basepython = python3
+deps = -r{toxinidir}/etc/requirements.txt
+commands =
+    sphinx-build -b html -n -d {envtmpdir}/doctrees -c {toxinidir}/docs ./docs/guides/onap-developer/how-to-use-docs/templates {toxinidir}/docs/_build/html/templates
+    echo "Generated docs available in {toxinidir}/docs/_build/html/templates"
+whitelist_externals =
+    echo
+
 [testenv:local]
 basepython = python3
 deps = -r{toxinidir}/etc/requirements.txt