diff options
| author |   Andrea Visnyei <andrea.visnyei@nokia.com> | 2020-12-09 12:26:35 +0100 |
|---|---|---|
| committer |   Eric Debeau <eric.debeau@orange.com> | 2021-05-06 15:36:12 +0200 |
| commit | 32d2daf4c1c9a01c6cc6e9b4218b9f4d2650b8e8 (patch) | |
| tree | 037bd4cf5220935b9f405d3db64e9b5b5e01eafe | |
| parent | c7d15886be96f3036709bb0acc4beb7169e8eec1 (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>
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 @@ -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 |