fix doc guide

Issue-ID: DOC-798

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

1 files changed, 77 insertions, 127 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 0e3abf2ce..cf58cefc9 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)
 
 Last Review/Update
-   2022/10/20
+   2022/10/24
 
 Initial Release
    2021/12/05
@@ -52,12 +52,6 @@ Author (Company)
 
 -------------------------------------------------------------------------------
 
-.. warning:: There are known issues with the build and preview function in
-             Vscode. This guide gets updated when a solution of the problem is
-             available. Please excuse any inconvenience.
-
--------------------------------------------------------------------------------
-
 .. contents:: Table of Contents
 
 -------------------------------------------------------------------------------
@@ -157,7 +151,7 @@ Maybe you need to force a snap-store update with the following commands:
    sudo snap refresh
 
 Open :guilabel:`Ubuntu Software` again and check the :guilabel:`Updates` tab
-for required actions. 
+for required actions.
 
 Screen Lock
 -----------
@@ -223,11 +217,8 @@ and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
 
 Install python3 related packages
 ================================
-..
-   .. important:: The main python3 package is preinstalled in Ubuntu. But please
-      ensure that python version 3.8 is also available on your system.
 
-.. important:: The main python3 package is preinstalled in Ubuntu
+.. important:: The main python3 package comes preinstalled with Ubuntu
 
 Open a :guilabel:`Terminal` window and update the package management system
 with ...
@@ -256,18 +247,6 @@ Check the python3 version with ...
 
    python3 -V
 
-..
-   Install additional python version 3.8 and utils with ...
-
-   .. code-block:: bash
- 
-      sudo apt install software-properties-common -y
-      sudo add-apt-repository ppa:deadsnakes/ppa -y
-      sudo apt update
-      sudo apt install -y python3.8
-      sudo apt install -y python3.8-distutils
-
-
 -------------------------------------------------------------------------------
 
 Install git and documentation related packages
@@ -359,40 +338,20 @@ Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
 
 -------------------------------------------------------------------------------
 
-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``. 
-
-.. important:: Currently an environment with python version 3.8 is required to
-   build docs properly.
-
-..
-   .. code-block:: bash
-
-      cd ~
-      mkdir environments
-      cd ~/environments
-      virtualenv -p /usr/bin/python3.8 onapdocs
-      cd ~/environments/onapdocs
-      source bin/activate
+Create working directory
+========================
 
+Create the working directory ``onapdocs`` in your home directory together with
+a ``repos`` directory to store various projects and versions. The full path is
+consequently ``~/onapdocs/repos``.
 
 .. 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)``.
+   mkdir onapdocs
+   cd onapdocs
+   mkdir repos
+   cd repos
 
 -------------------------------------------------------------------------------
 
@@ -407,7 +366,7 @@ Linux Foundation (LF) account with ...
 
 .. code-block:: bash
 
-   cd ~/environments/onapdocs
+   cd ~/onapdocs/repos
    git clone --branch master https://git.onap.org/doc/ ./doc
 
 -------------------------------------------------------------------------------
@@ -420,40 +379,24 @@ Clone repo
 
 .. code-block:: bash
 
-   cd ~/environments/onapdocs
+   cd ~/onapdocs/repos
    git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
 
 -------------------------------------------------------------------------------
 
-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
-   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.
+Install required Sphinx packages
+================================
 
-..
-   .. code-block:: bash
+.. important:: By using ``sudo pip ...`` you will see a message saying:
+   "*WARNING: Running pip as the 'root' user can result in broken permissions
+   and conflicting behaviour with the system package manager*". We try to avoid
+   this installation method in a later version of this guide.
 
-      pip install wheel \
-                  sphinxcontrib-spelling \
-                  pyenchant
- 
+Install required Sphinx packages with ...
 
 .. code-block:: bash
 
-   pip install wheel
-
+   sudo pip install wheel
 
 Continue with the installation of required packages. Use the file
 ``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
@@ -461,14 +404,14 @@ repository.
 
 .. code-block:: bash
 
-   pip install -r doc/etc/requirements-docs.txt
+   sudo pip install -r doc/etc/requirements-docs.txt
 
 -------------------------------------------------------------------------------
 
 Start VSC in the correct directory
 ==================================
 
-Start VSC (always) in the ``docs`` directory of your repository. For the
+Start VSC (always) in the ``docs`` directory of your repository. For the cloned
 ``doc`` repository used in this example do this with ...
 
 .. code-block:: bash
@@ -478,7 +421,7 @@ Start VSC (always) in the ``docs`` directory of your repository. For the
 
 .. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
 
-.. tip:: ``~/environments/onapdocs/doc/docs`` is now your
+.. tip:: ``~/onapdocs/repos/doc/docs`` is now your
    ``${workspaceFolder}`` because you have started VSC (``code .``) from here!
 
 -------------------------------------------------------------------------------
@@ -517,24 +460,39 @@ extension in the :guilabel:`Search Extensions in Marketplace` window.
 Press :guilabel:`Install` if you have found the required extension.
 
 .. important:: You will experience, that VSC asks you to install additional
-   components (e.g. the Esbonio Language Server, Trond Snekvik
-   reStructuredText Syntax Highlighting). It is important to allow VSC the
-   installation!
-
-
-Please install ...
+   components (e.g. Esbonio Language Server, reStructuredText Syntax
+   Highlighting). It is important to allow VSC the installation!
+
+
+Please manually install ...
+
++---------------------------------------+--------------------+------------+
+| IDENTIFIER (search)                   | NAME               | TESTED     |
++=======================================+====================+============+
+| ms-python.python                      | Python             | v2022.16.1 |
++---------------------------------------+--------------------+------------+
+| lextudio.restructuredtext             | reStructuredText   | v189.1.0   |
++---------------------------------------+--------------------+------------+
+| eamodio.gitlens                       | GitLens            | v13.0.3    |
++---------------------------------------+--------------------+------------+
+| streetsidesoftware.code-spell-checker | Code Spell Checker | v2.10.1    |
++---------------------------------------+--------------------+------------+
+| esbenp.prettier-vscode                | Prettier           | v9.9.0     |
++---------------------------------------+--------------------+------------+
+
+Together with the above extensions, the following software is automatically
+installed ...
+
++----------------------------+--------------------------------------+-------------+
+| IDENTIFIER (search)        | NAME                                 | TESTED      |
++============================+======================================+=============+
+| ms-python.vscode-pylance   | Pylance                              | v2022.10.30 |
++----------------------------+--------------------------------------+-------------+
+| several Jupyter Extensions | Jupyter ...                          | ...         |
++----------------------------+--------------------------------------+-------------+
+| snekvik.simple-rst         | reStructuredText Syntax highlighting | v1.5.2      |
++----------------------------+--------------------------------------+-------------+
 
-+---------------------------------------+--------------------------------------+-------------+
-| IDENTIFIER (search)                   | NAME                                 | TESTED      |
-+=======================================+======================================+=============+
-| ms-python.python                      | Python                               | v2022.14.0  |
-+---------------------------------------+--------------------------------------+-------------+
-| lextudio.restructuredtext             | reStructuredText                     | v189.1.0    |
-+---------------------------------------+--------------------------------------+-------------+
-| eamodio.gitlens                       | GitLens                              | v12.2.1     |
-+---------------------------------------+--------------------------------------+-------------+
-| streetsidesoftware.code-spell-checker | Code Spell Checker                   | v2.7.2      |
-+---------------------------------------+--------------------------------------+-------------+
 
 Close VSC and restart it using the ``code .`` command.
 
@@ -555,8 +513,6 @@ Values for the following parameters need to be changed:
 - Restructuredtext › Linter › Rst-lint: Executable Path
 - Restructuredtext › Linter › Rstcheck: Executable Path
 - Esbonio › Sphinx: Build Dir
-- Esbonio › Sphinx: Conf Dir
-- Esbonio › Sphinx: Src Dir
 - Restructuredtext: Styles
 
 
@@ -584,13 +540,9 @@ the listed values:
     * - restructuredtext.linter.rstcheck.executablePath
       - /usr/bin/doc8
     * - esbonio.sphinx.buildDir
-      - ${workspaceFolder}/_build/html
-    * - esbonio.sphinx.confDir
-      - ${workspaceFolder}
-    * - esbonio.sphinx.srcDir
-      - ${workspaceFolder}
+      - ${workspaceFolder}/_build
     * - restructuredtext.styles
-      - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css
+      - "/usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css"
 
 Close the :guilabel:`Extension Settings` window.
 
@@ -606,9 +558,7 @@ should now include the following entries:
        "restructuredtext.linter.doc8.executablePath": "/usr/bin/doc8",
        "restructuredtext.linter.rst-lint.executablePath": "/usr/bin/doc8",
        "restructuredtext.linter.rstcheck.executablePath": "/usr/bin/doc8",
-       "esbonio.sphinx.buildDir": "${workspaceFolder}/_build/html",
-       "esbonio.sphinx.confDir": "${workspaceFolder}",
-       "esbonio.sphinx.srcDir": "${workspaceFolder}", 
+       "esbonio.sphinx.buildDir": "${workspaceFolder}/_build",
        "restructuredtext.styles": [
          "/usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css"
        ]
@@ -655,11 +605,11 @@ Build documentation locally
 ---------------------------
 
 To build documentation locally use the ``tox`` command, check the output for
-error messages and check the files using your favorite browser. 
+error messages and check the files using your favorite browser.
 
 .. code-block:: bash
 
-    cd ~/environments/onapdocs/doc
+    cd ~/onapdocs/repos/doc
     tox
     ... (checks are executed, docs are build, check logging output) ...
     cd docs/_build/html
@@ -865,21 +815,21 @@ Backlog
 There are still some open topics or issues in this guide. They are subject
 for one of the upcoming releases.
 
- - fix issues with virtual environments using different python versions
- - consider ``pandoc`` in this guide?
- - 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)
- - add a table explaining the role of installed packages/extensions in every
-   section
+- fix issues with virtual environments using different python versions in VCS
+- consider ``pandoc`` in this guide?
+- 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)
+- add a table explaining the role of installed packages/extensions in every
+  section
 
 ..
    #########################################################################