update doc dev guide

Issue-ID: DOC-798

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

1 files changed, 102 insertions, 70 deletions

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
index 6b43ec82b..d64cdbdbe 100644
--- a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
+++ b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
@@ -42,7 +42,7 @@ Release Relevance
    11.x.x (Kohn) - 10.x.x (Jakarta)
 
 Last Review/Update
-   2022/09/01
+   2022/09/06
 
 Initial Release
    2021/12/05
@@ -78,6 +78,12 @@ Beginning with the 'Frankfurt' release of ONAP, the documentation structure has
 changed and the support of submodules was removed. Although large parts of this
 guide are valid for earlier releases, the relevance has been limited.
 
+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
+`Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
+and the `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information
+about all the prerequisite details.
+
 -------------------------------------------------------------------------------
 
 VM Configuration
@@ -197,7 +203,8 @@ and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
 Install python3 related packages
 ================================
 
-.. note:: The main python3 package is preinstalled in Ubuntu 20.04.
+.. important:: The main python3 package is preinstalled in Ubuntu 20.04. But
+   please ensure that you are using python version 3.8 or higher.
 
 Open a :guilabel:`Terminal` window and update the package management system
 with ...
@@ -243,7 +250,7 @@ Install the required packages with ...
                        jq \
                        tox
 
-Check the git version and the path of the sphinx-build executable ...
+Check git version and the path of the sphinx-build executable with ...
 
 .. code-block:: bash
 
@@ -258,64 +265,87 @@ Check the git version and the path of the sphinx-build executable ...
 
 -------------------------------------------------------------------------------
 
-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``.
+Install Visual Studio Code (VSC) and update applications
+========================================================
 
-.. code-block:: bash
+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.
 
-   cd ~
-   mkdir environments
-   cd ~/environments
-   python3 -m venv onapdocs
-   cd ~/environments/onapdocs
-   source bin/activate
+Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
+:guilabel:`vscode` (Visual Studio Code) and press :guilabel:`Install` to
+install the integrated development environment (IDE).
 
-To indicate that you are now working in an virtual environment, the prompt of
-your terminal has changed. Now it starts with ``(onapdocs)``.
+Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
+installed applications are up to date.
 
 -------------------------------------------------------------------------------
 
-Install required Sphinx packages in activated environment (I)
-=============================================================
+Configure ssh
+=============
 
-It is :strong:`important` to activate the ``onapdocs`` environment before you
-continue. If not already done, activate environment with ...
+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_{algorithm}`` and ``id_{algorithm}.pub``
 
-.. code-block:: bash
+.. warning:: If your ssh key has been generated using the RSA SHA-1 hash
+   algorithm, you may experience problems when connecting to other systems.
 
-   cd ~/environments/onapdocs
-   source bin/activate
+   The RSA SHA-1 hash algorithm has been quickly deprecated across operating
+   systems and SSH clients because of various security vulnerabilities,
+   with many of these technologies now outright denying the use of this
+   algorithm. You need to create new ssh keys using a more secure algorithm.
 
-To indicate that you are now working in an virtual environment, the prompt of
-your terminal has changed. Now it starts with ``(onapdocs)``.
+   You may try to temporarily enable the insecure RSA SHA-1 hash algorithm by
+   adding the line ``PubkeyAcceptedKeyTypes +ssh-rsa`` to your ssh ``config``
+   file.
 
-.. important:: Now you are installing packages only for the 'onapdocs' virtual
-   environment.
+.. tip:: Please refer to the
+   `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
+   for additional information.
+
+-------------------------------------------------------------------------------
+
+Configure git
+=============
+
+Configure ``git`` and ``git-review`` with ...
 
 .. code-block:: bash
 
-   pip3 install wheel
+   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.
+
+.. tip:: Please refer to the
+   `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
+   for additional information.
 
 -------------------------------------------------------------------------------
 
-Install Visual Studio Code (VSC) and update already installed applications
-==========================================================================
+Create virtual environment and activate
+=======================================
 
-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.
+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``.
 
-Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
-:guilabel:`code` (Visual Studio Code) and press :guilabel:`Install` to install
-the integrated development environment (IDE).
+.. code-block:: bash
 
-Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
-installed applications are up to date.
+   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)``.
 
 -------------------------------------------------------------------------------
 
@@ -338,42 +368,36 @@ Linux Foundation (LF) account with ...
 Clone example repo (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 ...
+Clone repo
+----------
 
 .. 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
+   cd ~/environments/onapdocs
+   git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
 
-Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
+-------------------------------------------------------------------------------
 
-Clone repo
-----------
+Install required Sphinx packages in activated environment
+=========================================================
+
+It is :strong:`important` to work in the ``onapdocs`` virtual environment. If
+not already done, activate environment with ...
 
 .. code-block:: bash
 
    cd ~/environments/onapdocs
-   git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
+   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 (II)
-==============================================================
+.. important:: Now you are installing packages only for the 'onapdocs' virtual
+   environment.
+
+.. code-block:: bash
+
+   pip3 install wheel
 
 Continue with the installation of required packages. Use the file
 ``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
@@ -640,11 +664,18 @@ Gerrit
 
 - `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
 
-Git
----
+Git/GitHub
+----------
 
-- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
+- `GitHub Authentication <https://docs.github.com/en/authentication>`__
 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
+- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
+
+Linux Foundation Release Engineering
+------------------------------------
+
+- `LF RelEng Documentation (recommended reading) <https://docs.releng.linuxfoundation.org>`__
+
 
 ONAP Documentation Procedures for Developers
 --------------------------------------------
@@ -665,12 +696,13 @@ ReadTheDocs
 -----------
 
 - `Documentation <https://docs.readthedocs.io/en/stable/>`__
+- `Tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`__
 - `GitHub <https://github.com/readthedocs/readthedocs.org/>`__
 
 ReadTheDocs Sphinx Theme
 ------------------------
 
-- `ReadTheDocs Sphinx Theme (Recommended Reading!) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
+- `ReadTheDocs Sphinx Theme (recommended reading) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
 - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
 
 reStructuredText