summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAndrea Visnyei <andrea.visnyei@nokia.com>2020-12-09 12:26:35 +0100
committerEric Debeau <eric.debeau@orange.com>2021-05-06 15:36:12 +0200
commit32d2daf4c1c9a01c6cc6e9b4218b9f4d2650b8e8 (patch)
tree037bd4cf5220935b9f405d3db64e9b5b5e01eafe
parentc7d15886be96f3036709bb0acc4beb7169e8eec1 (diff)
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>
-rw-r--r--docs/conf.py6
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/collections/platform-component.rst2
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/index.rst26
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst63
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst7
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst20
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst57
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst13
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst71
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst25
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/humaninterfaces.rst17
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst69
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst6
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst10
-rw-r--r--docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst30
-rw-r--r--docs/guides/onap-developer/index.rst6
-rw-r--r--tox.ini9
17 files changed, 326 insertions, 111 deletions
diff --git a/docs/conf.py b/docs/conf.py
index 2de736ec9..3025d0e62 100644
--- 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 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
diff --git a/tox.ini b/tox.ini
index 5807a8180..4bc8f3d65 100644
--- 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