Add guide for a doc dev system

Issue-ID: DOC-742

Signed-off-by: thmsdt <thomas.kulik@telekom.de>
Change-Id: Ie6071576bce613edaf50433b7b84b69b16e0e88c

6 files changed, 730 insertions, 0 deletions

diff --git a/docs/guides/onap-documentation/index.rst b/docs/guides/onap-documentation/index.rst
new file mode 100644
index 000000000..d9cdbad8f
--- /dev/null
+++ b/docs/guides/onap-documentation/index.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2021 Deutsche Telekom AG
+
+.. _ONAP_documentation_guides:
+
+Documentation Guides
+====================
+The following guides are provided for people who want to understand or
+contribute to the ONAP documentation project.
+
+Currently some content resides also in the Developer Guide. This is subject to
+be reviewed, updated and migrated to the ONAP Documenation Guide.
+
+.. toctree::
+   :maxdepth: 1
+
+   setup-of-a-doc-dev-system.rst
diff --git a/docs/guides/onap-documentation/media/PreviewOnRightPane_16x.svg b/docs/guides/onap-documentation/media/PreviewOnRightPane_16x.svg
new file mode 100644
index 000000000..eefaadfcc
--- /dev/null
+++ b/docs/guides/onap-documentation/media/PreviewOnRightPane_16x.svg
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 19.2.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 16 16" style="enable-background:new 0 0 16 16;" xml:space="preserve">
+<style type="text/css">
+	.icon_x002D_vs_x002D_bg{fill:#424242;}
+</style>
+<g id="canvas">
+</g>
+<g id="outline">
+</g>
+<g id="iconFg">
+</g>
+<g id="iconBg">
+	<path class="icon_x002D_vs_x002D_bg" d="M9,5h5v2.4c0.4,0.2,0.7,0.4,1,0.7V2H1v12h5.6L9,11.6V5z M2,13V5h5v8H2z M11.3,12.7
+		c0.4,0.2,0.8,0.3,1.2,0.3c1.4,0,2.5-1.1,2.5-2.5C15,9.1,13.9,8,12.5,8C11.1,8,10,9.1,10,10.5c0,0.4,0.1,0.8,0.3,1.2L8,14l1,1
+		L11.3,12.7z M11,10.5C11,9.7,11.7,9,12.5,9c0.8,0,1.5,0.7,1.5,1.5c0,0.8-0.7,1.5-1.5,1.5C11.7,12,11,11.3,11,10.5z"/>
+</g>
+</svg>
diff --git a/docs/guides/onap-documentation/media/files.svg b/docs/guides/onap-documentation/media/files.svg
new file mode 100644
index 000000000..f4b0ee6e4
--- /dev/null
+++ b/docs/guides/onap-documentation/media/files.svg
@@ -0,0 +1,3 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M17.5002 0H8.50024L7.00024 1.5V6H2.50024L1.00024 7.5V22.5699L2.50024 24H14.5702L16.0002 22.5699V18H20.7002L22.0002 16.5699V4.5L17.5002 0ZM17.5002 2.12L19.8802 4.5H17.5002V2.12ZM14.5002 22.5H2.50024V7.5H7.00024V16.5699L8.50024 18H14.5002V22.5ZM20.5002 16.5H8.50024V1.5H16.0002V6H20.5002V16.5Z" fill="#424242"/>
+</svg>
diff --git a/docs/guides/onap-documentation/media/gear.svg b/docs/guides/onap-documentation/media/gear.svg
new file mode 100644
index 000000000..0040bfcff
--- /dev/null
+++ b/docs/guides/onap-documentation/media/gear.svg
@@ -0,0 +1,3 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M9.1 4.4L8.6 2H7.4L6.9 4.4L6.2 4.7L4.2 3.4L3.3 4.2L4.6 6.2L4.4 6.9L2 7.4V8.6L4.4 9.1L4.7 9.9L3.4 11.9L4.2 12.7L6.2 11.4L7 11.7L7.4 14H8.6L9.1 11.6L9.9 11.3L11.9 12.6L12.7 11.8L11.4 9.8L11.7 9L14 8.6V7.4L11.6 6.9L11.3 6.1L12.6 4.1L11.8 3.3L9.8 4.6L9.1 4.4ZM9.4 1L9.9 3.4L12 2.1L14 4.1L12.6 6.2L15 6.6V9.4L12.6 9.9L14 12L12 14L9.9 12.6L9.4 15H6.6L6.1 12.6L4 13.9L2 11.9L3.4 9.8L1 9.4V6.6L3.4 6.1L2.1 4L4.1 2L6.2 3.4L6.6 1H9.4ZM10 8C10 9.1 9.1 10 8 10C6.9 10 6 9.1 6 8C6 6.9 6.9 6 8 6C9.1 6 10 6.9 10 8ZM8 9C8.6 9 9 8.6 9 8C9 7.4 8.6 7 8 7C7.4 7 7 7.4 7 8C7 8.6 7.4 9 8 9Z" fill="#424242"/>
+</svg>
diff --git a/docs/guides/onap-documentation/media/view-app-grid-symbolic.svg b/docs/guides/onap-documentation/media/view-app-grid-symbolic.svg
new file mode 100644
index 000000000..c0fd3424b
--- /dev/null
+++ b/docs/guides/onap-documentation/media/view-app-grid-symbolic.svg
@@ -0,0 +1,3 @@
+<svg height="16" width="16" xmlns="http://www.w3.org/2000/svg">
+    <path d="M3.805 3C3.268 3 3 3 3 3.625v.75C3 5 3.268 5 3.805 5h.39C4.732 5 5 5 5 4.375v-.75C5 3.022 4.732 3 4.195 3zm4 0C7.268 3 7 3 7 3.625v.75C7 5 7.268 5 7.805 5h.39C8.732 5 9 5 9 4.375v-.75C9 3.022 8.732 3 8.195 3zm4 0C11.268 3 11 3 11 3.625v.75c0 .625.268.625.805.625h.39C12.732 5 13 5 13 4.375v-.75c0-.603-.268-.625-.805-.625zm-8 4C3.268 7 3 7 3 7.625v.75C3 9 3.268 9 3.805 9h.39C4.732 9 5 9 5 8.375v-.75C5 7.022 4.732 7 4.195 7zm4 0C7.268 7 7 7 7 7.625v.75C7 9 7.268 9 7.805 9h.39C8.732 9 9 9 9 8.375v-.75C9 7.022 8.732 7 8.195 7zm4 0C11.268 7 11 7 11 7.625v.75c0 .625.268.625.805.625h.39C12.732 9 13 9 13 8.375v-.75c0-.603-.268-.625-.805-.625zm-8 4C3.268 11 3 11 3 11.625v.75c0 .625.268.625.805.625h.39C4.732 13 5 13 5 12.375v-.75c0-.603-.268-.625-.805-.625zm4 0C7.268 11 7 11 7 11.625v.75c0 .625.268.625.805.625h.39C8.732 13 9 13 9 12.375v-.75c0-.603-.268-.625-.805-.625zm4 0c-.537 0-.805 0-.805.625v.75c0 .625.268.625.805.625h.39c.537 0 .805 0 .805-.625v-.75c0-.603-.268-.625-.805-.625z" style="marker:none" color="#000" overflow="visible" fill="gray"/>
+</svg>
diff --git a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
new file mode 100644
index 000000000..be2d29072
--- /dev/null
+++ b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
@@ -0,0 +1,684 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License. http://creativecommons.org/licenses/by/4.0
+.. Copyright (C) 2021 Deutsche Telekom AG
+
+
+
+*******************************************
+Setup of a Documentation Development System
+*******************************************
+
+
+..
+   #########################################################################
+   HOW TO FILL THIS SECTION:
+
+   Release Relevance
+      Name the ONAP release(s) where this document has a relevance.
+      ONAP release number (ONAP release name starting with a capital letter)
+      Examples:
+      8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
+      7.0.1 (Guilin) - 3.0.0 (Casablanca), 1.0.0 (Amsterdam)
+
+   Last Review/Update
+      Date of last review and/or update of this document.
+      Add "none" for a new document. Add concrete date if reviewed/updated.
+      Use en-US format (mm/dd/yyyy).
+
+   Initial Release
+      Initial release date of this document.
+      Use en-US format (mm/dd/yyyy).
+
+   Author (Company)
+      Name of the author and company name. Use comma to separate.
+      Example:
+      Jane Doe (ACME), John Doe (ACME)
+
+   ! PLEASE DO NOT CHANGE THE STRUCTURE OF THIS SECTION.
+   ! PLEASE ADD ONLY REQUESTED INFORMATION BELOW!
+   #########################################################################
+
+Release Relevance
+   8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
+
+Last Review/Update
+   none
+
+Initial Release
+   05/12/2021
+
+Author (Company)
+   Thomas Kulik (Deutsche Telekom AG)
+
+-------------------------------------------------------------------------------
+
+.. contents:: Table of Contents
+
+-------------------------------------------------------------------------------
+
+Introduction
+============
+
+Formal ONAP documentation uses the reStructuredText markup language and the
+files have an ``.rst`` extension. They are part of almost every ONAP project
+and can be found in the ``docs`` directory. The files are automatically
+processed and you find the final ONAP documentation build hosted on
+`ReadTheDocs <https://docs.onap.org>`__.
+
+This guide provides a detailed description to set up a system suitable to
+create, check and preview documentation locally. The targeted readership is
+beginners and people interested in creating documentation.
+
+The guide describes the setup of a development system from scratch using the
+Ubuntu Desktop version installed in a virtual machine. It includes all required
+steps and also some optional ones that may ease your daily work with this
+development system. Feel free to adapt it to your needs.
+
+-------------------------------------------------------------------------------
+
+VM Configuration
+================
+
+.. note:: This section is for information only and should not be understood as
+          a requirement.
+
+Ubuntu Image
+------------
+
++----------------------------------------+
+| ubuntu-20.04.2.0-desktop-amd64.iso     |
++----------------------------------------+
+
+Please check what image must be used for your type of hardware.
+
+VM Configuration
+----------------
+
++-------------------------+------------+
+| Memory                  | 8 GB       |
++-------------------------+------------+
+| Processors / Cores each | 2 / 2      |
++-------------------------+------------+
+| Hard Disk               | 64 GB      |
++-------------------------+------------+
+
+Depending on your requirements you can modify the values for virtual memory,
+processors, cores or hard disk space.
+
+VM Setup
+--------
+
+Follow the instructions of your virtualization solution to install Ubuntu in a
+virtual machine. Log in after the installation has finished.
+
+-------------------------------------------------------------------------------
+
+Ubuntu Configuration
+====================
+
+.. note:: This section is optional and should not be understood as a
+   requirement.
+
+Finding Applications
+--------------------
+
+The following actions are performed on the Ubuntu desktop. You may use the
+desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
+the bottom left corner) to find the required applications. Later on you need to
+start also a :guilabel:`Terminal` window from here.
+
+Software Updates
+----------------
+
+Open :guilabel:`Software Updater` and update already installed Ubuntu packages.
+You may need to restart the system afterwards.
+
+Language Support
+----------------
+
+Open :guilabel:`Language Support`. You are asked to complete the installation.
+Select the :guilabel:`Install` button to complete. Continue in the
+:guilabel:`Language Support` window and open
+:guilabel:`Install / Remove Languages`. Then select your preferred
+:guilabel:`<LANGUAGE>`. Choose :guilabel:`Apply` to install the additional
+language.
+
+Regional Formats
+----------------
+
+Continue to the :guilabel:`Regional Formats` tab. Select a
+:guilabel:`<FORMAT>` to show e.g. date, time and numbers in your preferred
+format. Press :guilabel:`Close` to close the window.
+
+Input Sources
+-------------
+
+To change the keyboard layout used e.g. in command line windows, open
+:guilabel:`Settings`. Navigate to :guilabel:`Region & Language`. At
+:guilabel:`Input Sources` press the :guilabel:`+` sign. Select your preferred
+:guilabel:`<INPUTSOURCE>` and use :guilabel:`Add` to add it. Move it to the top
+of the list using drag and drop. Close the window. You may need to logout from
+the UI and login again to make your changes effective.
+
+Screen Lock
+-----------
+
+Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
+:guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
+and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
+window.
+
+-------------------------------------------------------------------------------
+
+Disable sudo password for your user
+===================================
+
+.. warning:: This section is optional and should not be understood as a
+   requirement. Disabling password authentication for all commands is very
+   convenient at use **but it strongly exposes your system to malicious code**.
+   For a system dedicated to development it might be OK, but not for a
+   production system! Handle with care. You have been warned.
+
+Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ...
+
+.. code-block:: bash
+
+   sudo visudo
+
+and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
+``<USER>`` with your user name.
+
+-------------------------------------------------------------------------------
+
+Install python3 related packages
+================================
+
+.. note:: The main python3 package is preinstalled in Ubuntu 20.04.
+
+Open a :guilabel:`Terminal` window and update the package management system
+with ...
+
+.. code-block:: bash
+
+   cd ~
+   sudo apt update
+   sudo apt -y upgrade
+
+Install python3 related packages with ...
+
+.. code-block:: bash
+
+   sudo apt install -y python3-pip
+   sudo apt install -y build-essential
+   sudo apt install -y libssl-dev
+   sudo apt install -y libffi-dev
+   sudo apt install -y python3-dev
+   sudo apt install -y python3-venv
+
+
+Check the python3 version with ...
+
+.. code-block:: bash
+
+   python3 -V
+
+-------------------------------------------------------------------------------
+
+Install git and documentation related packages
+==============================================
+
+Install the required packages with ...
+
+.. code-block:: bash
+
+   sudo apt install -y git
+   sudo apt install -y git-review
+   sudo apt install -y python3-sphinx
+   sudo apt install -y python3-doc8
+   sudo apt install -y curl
+   sudo apt install -y jq
+
+Check the git version with ...
+
+.. code-block:: bash
+
+   git --version
+
+-------------------------------------------------------------------------------
+
+Create virtual environment and activate
+=======================================
+
+In this guide, virtual environments are generally located in your home
+directory under ``~/environments``. For the development of ONAP documentation
+the virtual environment ``onapdocs`` is created. The full path is consequently
+``~/environments/onapdocs``.
+
+.. code-block:: bash
+
+   cd ~
+   mkdir environments
+   cd ~/environments
+   python3 -m venv onapdocs
+   cd ~/environments/onapdocs
+   source bin/activate
+
+To indicate that you are now working in an virtual environment, the prompt of
+your terminal has changed. Now it starts with ``(onapdocs)``.
+
+-------------------------------------------------------------------------------
+
+Install required Sphinx packages in activated environment
+=========================================================
+
+It is :strong:`important` to activate the ``onapdocs`` environment before you
+continue. If not already done, activate environment with ...
+
+.. code-block:: bash
+
+   cd ~/environments/onapdocs
+   source bin/activate
+
+To indicate that you are now working in an virtual environment, the prompt of
+your terminal has changed. Now it starts with ``(onapdocs)``.
+
+.. important:: Now you are installing packages only for the 'onapdocs' virtual
+   environment.
+
+.. code-block:: bash
+
+   pip3 install wheel
+   pip3 install sphinx_rtd_theme
+   pip3 install sphinxcontrib-blockdiag
+   pip3 install sphinxcontrib-needs
+   pip3 install sphinxcontrib-nwdiag
+   pip3 install sphinxcontrib-seqdiag
+   pip3 install sphinxcontrib-swaggerdoc
+   pip3 install sphinxcontrib-plantuml
+   pip3 install lfdocs-conf
+
+   which sphinx-build
+
+.. tip:: Remember the path
+   ``/home/<USER>/environments/onapdocs/bin/sphinx-build``, you need it later
+   to configure a VSC extension.
+
+-------------------------------------------------------------------------------
+
+Install Visual Studio Code (VSC) and update already installed applications
+==========================================================================
+
+The following actions are performed on the Ubuntu desktop. You may use the
+desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
+the bottom left corner) to find the required applications.
+
+Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
+:guilabel:`Visual Studio Code` and press :guilabel:`Install` to install the
+integrated development environment (IDE).
+
+Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
+installed applications are up to date.
+
+-------------------------------------------------------------------------------
+
+Clone example repo and start VSC (no LF account)
+================================================
+
+Clone repo
+----------
+
+For a quick start you can clone e.g. the ``doc`` repository even without a
+Linux Foundation (LF) account with ...
+
+.. code-block:: bash
+
+   cd ~/environments/onapdocs
+   git clone --branch master https://git.onap.org/doc/ ./doc
+
+Start VSC
+---------
+
+Start VSC in the ``doc`` repo directory with ...
+
+.. code-block:: bash
+
+   cd doc
+   code .
+
+.. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}``
+   because you have started VSC (``code``) from here!
+
+-------------------------------------------------------------------------------
+
+Clone example repo and start VSC (LF account used)
+==================================================
+
+Prerequisite configuration
+--------------------------
+
+If you plan to contribute to the ONAP community and you want to submit changes
+to a specific project later on, please refer to the
+`ONAP Developer Wiki <https://wiki.onap.org>`__ to get information about all
+the prerequisite details.
+
+If you already have a LF account and you have shared your public ssh key you
+can finalize the configuration of this development system by updating your ssh
+configuration in the ``~/.ssh`` directory by copying over ``config``,
+``id_rsa`` and ``id_rsa.pub``
+
+In addition you configure ``git`` and ``git-review`` with ...
+
+.. code-block:: bash
+
+   git config --global user.email "<GIT-EMAIL>"
+   git config --global user.name "<GIT-USER>"
+   git config --global --add gitreview.username "<GIT-USER>"
+   git config --global gitreview.remote origin
+
+Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
+
+Clone repo
+----------
+
+.. code-block:: bash
+
+   cd ~/environments/onapdocs
+   git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
+
+Start VSC
+---------
+
+Start VSC in the ``doc`` repo directory with ...
+
+.. code-block:: bash
+
+   cd doc
+   code .
+
+.. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}``
+   because you have started VSC (``code``) from here!
+
+-------------------------------------------------------------------------------
+
+Disable Telemetry of VSC
+========================
+
+In case you want to disable telemetry functionality of Visual Studio Code, open
+:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
+search for ``telemetry``. Then uncheck
+:guilabel:`Telemetry: Enable Crash Reporter` and
+:guilabel:`Telemetry: Enable Telemetry`
+
+.. warning:: Extensions may be collecting their own usage data and are not
+   controlled by the ``telemetry.enableTelemetry`` setting. Consult the
+   specific extension's documentation to learn about its telemetry
+   reporting and whether it can be disabled. See also
+   https://code.visualstudio.com/docs/getstarted/telemetry
+
+-------------------------------------------------------------------------------
+
+Install VSC extensions and configure reStructuredText extension
+===============================================================
+
+Install VSC extensions
+----------------------
+
+Extension bring additional power to Visual Studio Code. To search and install
+them, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Extensions`
+or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the
+extension in the :guilabel:`Search Extensions in Marketplace` window.
+Press :guilabel:`Install` if you have found the required extension.
+
+Please install ...
+
++--------------------+-----------------------------------------+
+| Python             | ms-python.python                        |
++--------------------+-----------------------------------------+
+| reStructuredText   | lextudio.restructuredtext               |
++--------------------+-----------------------------------------+
+| Code Spell Checker | streetsidesoftware.code-spell-checker   |
++--------------------+-----------------------------------------+
+| Prettier           | esbenp.prettier-vscode                  |
++--------------------+-----------------------------------------+
+| GitLens            | eamodio.gitlens                         |
++--------------------+-----------------------------------------+
+
+Configure reStructuredText extension
+------------------------------------
+
+To configure ``reStructuredText`` extension, open :guilabel:`File` >
+:guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut
+``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the
+:guilabel:`Search Extensions in Marketplace` window. After you have found the
+extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
+bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
+all the parameters. Change the following ones:
+
+ :strong:`Restructuredtext › Linter: Executable Path`
+  ``/usr/bin/doc8``
+
+ :strong:`Restructuredtext › Linter: Name`
+  ``doc8``
+
+ :strong:`Restructuredtext: Sphinx Build Path`
+  ``/home/<USER>/environments/onapdocs/bin/sphinx-build``
+
+Replace ``<USER>`` with your user name.
+
+Only in case the preview creates an error message, try ...
+
+  :strong:`Restructuredtext: Conf Path`
+   ``${workspaceFolder}/docs``
+
+Close the :guilabel:`Extension Settings` window.
+
+-------------------------------------------------------------------------------
+
+Open a .rst file and preview it in VSC
+======================================
+
+Open .rst file
+--------------
+
+Select :guilabel:`View` > :guilabel:`Explorer`. Alternatively you can use the
+|FileExpl| symbol in the upper left corner. Expand the ``docs`` folder by
+clicking on the ``>`` symbol. Select the file ``index.rst``. The code shows up
+in the right pane window of VSC.
+
+Problem Window
+--------------
+
+You may see problems with the reStructuredText markup because the code is
+underlined in various colors. For the details select :guilabel:`View` >
+:guilabel:`Problems` to open an additional window at the bottom of VSC.
+
+When you select a specific entry in the problem list, the code window is
+updated to show the related line in the code.
+
+Preview
+-------
+
+Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top
+right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window
+on the right hand side. This may take a few seconds. The preview shows up and
+renders the ``index.rst`` as it would look like on ReadTheDocs.
+
+Tips and Tricks
+---------------
+
+The learnings are ...
+
+.. tip::
+   - Start VSC always in the ``docs`` directory of the repository. Use the
+     command ``code .``. Then navigate via VSC's :guilabel:`Explorer`
+     |FileExpl| to the directory which contains the file you like to edit. VSC
+     may ask you, which ``conf.py`` VSC should use. Choose the one which
+     resides in the directory where you have started VSC. Check also the (blue)
+     bottom line of VSC. There you see which ``conf.py`` is currently in use.
+     The content of ``conf.py`` affects how the documentation is presented.
+   - VSC may claim that some packages require an update. This can be easily
+     fixed. VSC offers automatically to install or update the package.
+   - VSC may ask you to install ``snooty``. Please install.
+   - Select the correct environment in the (blue) bottom line
+     ``'onapdocs':venv``. Have also a view on the other interesting
+     information (e.g. the ``conf.py`` which is currently in use).
+   - First, close and reopen preview if preview is not shown properly.
+   - Second, close and reopen VSC if preview is not shown properly.
+   - Save your file if an error does not disappear after you have corrected it.
+   - You can not navigate within the document structure by clicking the links
+     in the preview. You always have to choose the correct file in the VSC
+     :guilabel:`Explorer` window.
+
+That's it!
+----------
+
+Congratulations, well done! You have configured a system well suited to
+develop ONAP documentation and to master the challenges of reStructuredText.
+Now have a look at all the different elements of reStructuredText and learn how
+to use them properly. Or maybe you like to do some optional configurations at
+your system first.
+
+-------------------------------------------------------------------------------
+
+Optional VSC Configuration
+==========================
+
+Ruler
+-----
+
+To add a ruler that indicates the line end at 79 characters, open
+:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
+``ruler`` in the :guilabel:`Search settings` field. In
+:guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add
+the value ``79``. The result should look like this:
+
+.. code-block:: bash
+
+    "editor.rulers": [
+        79
+    ]
+
+-------------------------------------------------------------------------------
+
+Miscellaneous
+=============
+
+.. note:: This section is optional and should not be understood as a
+   requirement.
+
+Firefox Add-ons
+---------------
+
+Open :guilabel:`Add-Ons and Themes`, then search and install the following
+add-ons:
+
++----------------------------+-------------------------------+
+| I don't care about cookies | Get rid of cookie warnings.   |
++----------------------------+-------------------------------+
+| UBlock Origin              | A wide-spectrum blocker.      |
++----------------------------+-------------------------------+
+| LastPass Password Manager  | Used in the Linux Foundation. |
++----------------------------+-------------------------------+
+
+ReText Editor
+-------------
+
+Install this simple editor with ...
+
+.. code-block:: bash
+
+   sudo apt install -y retext
+
+-------------------------------------------------------------------------------
+
+Helpful Resources
+=================
+
+This is a collection of helpful resources if you want to extend and deepen your
+knowledge.
+
+Python
+------
+
+- `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__
+- `How To Install Python 3 and Set Up a Programming Environment on an Ubuntu 20.04 Server <https://www.digitalocean.com/community/tutorials/how-to-install-python-3-and-set-up-a-programming-environment-on-an-ubuntu-20-04-server>`__
+- `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__
+- `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
+- `Linux Foundation Docs Conf <https://pypi.org/project/lfdocs-conf/>`__
+
+reStructuredText
+----------------
+
+- `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__
+- `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
+- `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
+- `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
+
+ReadTheDocs Sphinx Theme
+------------------------
+
+- `ReadTheDocs Sphinx Theme (highly recommended) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
+- `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
+
+Visual Studio Code (VSC)
+------------------------
+
+- `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__
+- `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
+- `VSC Icons <https://github.com/microsoft/vscode-icons>`__
+
+Git
+---
+
+- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
+
+Documentation
+-------------
+
+- `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
+
+-------------------------------------------------------------------------------
+
+Backlog
+=======
+
+There are still some open topics or issues in this guide. They are subject
+for one of the upcoming releases.
+
+ - consider ``pandoc`` in this guide?
+ - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build
+   Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives?
+ - link to full ``ssh`` install/config?
+ - link to full ``git`` install/config?
+ - how to limit line width to improve readability? setting in conf.py?
+ - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
+   :kbd:`X` Is this a problem in the RTD theme?
+ - use ``menuselection``
+   :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
+ - evaluate and add VSC extension to "draw" tables in an aided way
+ - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
+ - find the reason for VSC error message
+   ``Substitution definition "ShowApp" empty or invalid.``
+ - find the reason for VSC error message
+   ``Unexpected indentation``
+ - find a solution to wrap lines in VSC automatically (79 chars limit)
+ - evaluate ``snooty`` and describe functionality (build in? not a extension?)
+ - add a table explaining the role of installed packages/extensions in every
+   section
+
+..
+   #########################################################################
+   EMBEDDED PICTURES & ICONS BELOW
+   #########################################################################
+
+.. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
+   :width: 20
+
+.. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
+   :width: 20
+
+.. |FileExpl| image:: ./media/files.svg
+   :width: 20
+
+.. |GearSymb| image:: ./media/gear.svg
+   :width: 20