From 21d59414fca273aade30aa4209aca9bb35a5f78f Mon Sep 17 00:00:00 2001 From: thmsdt Date: Tue, 2 Aug 2022 13:28:17 +0200 Subject: update and rearrange documentation related content Issue-ID: DOC-798 Signed-off-by: thmsdt Change-Id: Id454ec5f09903efb81123669e6eb024f21a08797 --- .../templates/sections/administration.rst | 69 ----------- .../templates/sections/architecture.rst | 28 ----- .../how-to-use-docs/templates/sections/build.rst | 27 ----- .../templates/sections/configuration.rst | 62 ---------- .../templates/sections/consumedapis.rst | 13 --- .../templates/sections/delivery.rst | 53 --------- .../how-to-use-docs/templates/sections/design.rst | 32 ------ .../templates/sections/installation.rst | 73 ------------ .../how-to-use-docs/templates/sections/logging.rst | 22 ---- .../templates/sections/offeredapis.rst | 14 --- .../templates/sections/release-notes.rst | 127 --------------------- .../templates/sections/userinterfaces.rst | 30 ----- 12 files changed, 550 deletions(-) delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/release-notes.rst delete mode 100644 docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst (limited to 'docs/guides/onap-developer/how-to-use-docs/templates/sections') 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 deleted file mode 100644 index 841a55291..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/administration.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. 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 `_. - - -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-developer/how-to-use-docs/templates/sections/architecture.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst deleted file mode 100644 index d9a895a38..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/architecture.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/build.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst deleted file mode 100644 index 0fcf3153f..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/build.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/configuration.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst deleted file mode 100644 index 6d1ec29ba..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/configuration.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. 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 - -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 deleted file mode 100644 index 3a0cd6ad1..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/consumedapis.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/delivery.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst deleted file mode 100644 index 32f8450cc..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/delivery.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/design.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst deleted file mode 100644 index 66c5f3651..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/design.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/installation.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst deleted file mode 100644 index deac057b1..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/installation.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/logging.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst deleted file mode 100644 index 5662acb1f..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/logging.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/offeredapis.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst deleted file mode 100644 index fbb454a94..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/offeredapis.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. 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-developer/how-to-use-docs/templates/sections/release-notes.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/release-notes.rst deleted file mode 100644 index 11f38fed9..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/release-notes.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. 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: - -*********************** - 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 ```` release. - -Summary -======= - - - - -Release Data -============ - -+--------------------------------------+--------------------------------------+ -| **Project** | | -| | | -+--------------------------------------+--------------------------------------+ -| **Docker images** | make sure you include all docker | -| | images including the | -| | release version | -| | | -+--------------------------------------+--------------------------------------+ -| **Release designation** | | -| | | -+--------------------------------------+--------------------------------------+ - - -New features ------------- - - - -**Bug fixes** - -- `CIMAN-65 `_ and a sentence explaining - what this defect is addressing. - -**Known Issues** - -- `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, 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-developer/how-to-use-docs/templates/sections/userinterfaces.rst b/docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst deleted file mode 100644 index 0f6a6cb38..000000000 --- a/docs/guides/onap-developer/how-to-use-docs/templates/sections/userinterfaces.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. 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. -- cgit 1.2.3-korg