Merge "Update doc/tools"

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 be2d290..bdbc843 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
@@ -42,7 +42,7 @@ Release Relevance
    8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
 
 Last Review/Update
-   none
+   06/02/2021
 
 Initial Release
    05/12/2021
@@ -59,14 +59,8 @@ Author (Company)
 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
+create, check and preview documentation locally. The targeted readership are
 beginners and people interested in creating documentation.
 
 The guide describes the setup of a development system from scratch using the
@@ -74,6 +68,12 @@ 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.
 
+In general, 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>`__.
+
 -------------------------------------------------------------------------------
 
 VM Configuration
@@ -296,6 +296,7 @@ your terminal has changed. Now it starts with ``(onapdocs)``.
    pip3 install sphinxcontrib-swaggerdoc
    pip3 install sphinxcontrib-plantuml
    pip3 install lfdocs-conf
+   pip3 install pylint
 
    which sphinx-build
 
@@ -431,17 +432,17 @@ 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                         |
-+--------------------+-----------------------------------------+
++-----------------------+-----------------------------------------+
+| Python                | ms-python.python                        |
++-----------------------+-----------------------------------------+
+| reStructuredText      | lextudio.restructuredtext               |
++-----------------------+-----------------------------------------+
+| Code Spell Checker    | streetsidesoftware.code-spell-checker   |
++-----------------------+-----------------------------------------+
+| Prettier              | esbenp.prettier-vscode                  |
++-----------------------+-----------------------------------------+
+| GitLens               | eamodio.gitlens                         |
++-----------------------+-----------------------------------------+
 
 Configure reStructuredText extension
 ------------------------------------
@@ -543,8 +544,8 @@ your system first.
 Optional VSC Configuration
 ==========================
 
-Ruler
------
+Add Ruler
+---------
 
 To add a ruler that indicates the line end at 79 characters, open
 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
@@ -558,6 +559,15 @@ the value ``79``. The result should look like this:
         79
     ]
 
+Disable Synchronized Scrolling of Editor and Preview
+----------------------------------------------------
+
+To disable the synchronized scrolling of editor and preview, open
+:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
+search for ``Restructuredtext › Preview: Scroll``. Then uncheck
+:guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
+:guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
+
 -------------------------------------------------------------------------------
 
 Miscellaneous
@@ -572,13 +582,13 @@ 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. |
-+----------------------------+-------------------------------+
++------------------------------+-------------------------------+
+| 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
 -------------
@@ -597,6 +607,16 @@ Helpful Resources
 This is a collection of helpful resources if you want to extend and deepen your
 knowledge.
 
+Documentation
+-------------
+
+- `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
+
+Git
+---
+
+- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
+
 Python
 ------
 
@@ -606,6 +626,12 @@ Python
 - `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/>`__
 
+ReadTheDocs Sphinx Theme
+------------------------
+
+- `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
 ----------------
 
@@ -614,11 +640,10 @@ reStructuredText
 - `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
-------------------------
+Ubuntu
+------
 
-- `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>`__
+- `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
 
 Visual Studio Code (VSC)
 ------------------------
@@ -627,16 +652,6 @@ Visual Studio Code (VSC)
 - `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