remove submodules content from doc dev guide

[doc.git] / docs / guides / onap-documentation / setup-of-a-doc-dev-system.rst

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 6be2c67..424341b 100644 (file)
--- a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
+++ b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
@@ -39,10 +39,10 @@ Setup of a Documentation Development System
    #########################################################################
 
 Release Relevance
-   10.x.x (Jakarta) - 6.x.x (Frankfurt)
+   11.x.x (Kohn) - 10.x.x (Jakarta)
 
 Last Review/Update
-   31/03/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 ...
@@ -292,13 +293,9 @@ your terminal has changed. Now it starts with ``(onapdocs)``.
 .. code-block:: bash
 
    pip3 install wheel
-   pip3 install lfdocs-conf
 
    which sphinx-build
 
-.. note:: The ``lfdocs-conf`` package requires multiple, additional libraries.
-          They are loaded automatically.
-
 .. tip:: Remember the path
    ``/home/<USER>/environments/onapdocs/bin/sphinx-build``, you need it later
    to configure a VSC extension.
@@ -370,7 +367,21 @@ Clone repo
 .. code-block:: bash
 
    cd ~/environments/onapdocs
-   git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
+   git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
+
+-------------------------------------------------------------------------------
+
+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
 
 -------------------------------------------------------------------------------
 
@@ -444,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
 ------------------------------------
@@ -621,11 +634,23 @@ Documentation
 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
 - `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
 
+Gerrit
+------
+
+- `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
+
 Git
 ---
 
+- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
 
+ONAP Documentation Procedures for Developers
+--------------------------------------------
+
+- `Procedure #1 for the ONAP Documentation Team <https://wiki.onap.org/x/-IpkBg>`__
+- `Procedure #2 for all other ONAP Project Teams <https://wiki.onap.org/x/w4IEBw>`__
+
 Python
 ------
 
@@ -633,7 +658,7 @@ Python
 - `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/>`__
+- `Linux Foundation Docs Conf (obsolete) <https://pypi.org/project/lfdocs-conf/>`__
 
 ReadTheDocs
 -----------
@@ -689,6 +714,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?