Merge "add missing content to doc dev setup guide"

1 files changed, 34 insertions, 16 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 12f5ebcde..ee0455517 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
-   02/08/2022
+   23/08/2022
 
 Initial Release
    05/12/2021
@@ -212,12 +212,12 @@ 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
+   sudo apt install -y python3-pip \
+                       build-essential \
+                       libssl-dev \
+                       libffi-dev \
+                       python3-dev \
+                       python3-venv
 
 
 Check the python3 version with ...
@@ -235,12 +235,13 @@ 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
+   sudo apt install -y git \
+                       git-review \
+                       python3-sphinx \
+                       python3-doc8 \
+                       curl \
+                       jq \
+                       tox
 
 Check the git version with ...
 
@@ -272,8 +273,8 @@ your terminal has changed. Now it starts with ``(onapdocs)``.
 
 -------------------------------------------------------------------------------
 
-Install required Sphinx packages in activated environment
-=========================================================
+Install required Sphinx packages in activated environment (I)
+=============================================================
 
 It is :strong:`important` to activate the ``onapdocs`` environment before you
 continue. If not already done, activate environment with ...
@@ -370,6 +371,20 @@ Clone repo
 
 -------------------------------------------------------------------------------
 
+Install required Sphinx packages in activated environment (II)
+==============================================================
+
+Continue with the installation of required packages. Use the file
+``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
+repository.
+
+.. code-block:: bash
+
+   cd ~/environments/onapdocs
+   sudo pip install -r doc/etc/requirements-docs.txt
+
+-------------------------------------------------------------------------------
+
 Start VSC in the correct directory
 ==================================
 
@@ -440,7 +455,9 @@ Please install ...
 
 .. warning:: Use the reStructuredText extension version 169.0.0 or lower to
    avoid problems with the preview. You need to downgrade after the initial
-   installation.
+   installation. This can be done by using 
+   :guilabel:`Uninstall` > :guilabel:`Install Another Version...` in the VSC
+   extension management.
 
 Configure reStructuredText extension
 ------------------------------------
@@ -691,6 +708,7 @@ for one of the upcoming releases.
  - consider ``pandoc`` in this guide?
  - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build
    Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives?
+ - VSC extension configuration: Difference between "Workspace" and "User"?
  - link to full ``ssh`` install/config?
  - link to full ``git`` install/config?
  - how to limit line width to improve readability? setting in conf.py?