Code Review / doc.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
Update "Setup of a Documentation Development System"
[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 be2d290..b8b4a45 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
    #########################################################################
 
 Release Relevance
-   8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
+   9.0.0 (Istanbul) - 6.0.0 (Frankfurt)
 
 Last Review/Update
 
 Last Review/Update
-   none
+   10/05/2021
 
 Initial Release
    05/12/2021
 
 Initial Release
    05/12/2021
@@ -59,14 +59,8 @@ Author (Company)
 Introduction
 ============
 
 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
 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
 beginners and people interested in creating documentation.
 
 The guide describes the setup of a development system from scratch using the
@@ -74,6 +68,16 @@ 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.
 
 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>`__.
+
+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.
+
 -------------------------------------------------------------------------------
 
 VM Configuration
 -------------------------------------------------------------------------------
 
 VM Configuration
@@ -85,9 +89,9 @@ VM Configuration
 Ubuntu Image
 ------------
 
 Ubuntu Image
 ------------
 
-+----------------------------------------+
-| ubuntu-20.04.2.0-desktop-amd64.iso     |
-+----------------------------------------+
++--------------------------------------+
+| ubuntu-20.04.3-desktop-amd64.iso     |
++--------------------------------------+
 
 Please check what image must be used for your type of hardware.
 
 
 Please check what image must be used for your type of hardware.
 
@@ -288,17 +292,13 @@ your terminal has changed. Now it starts with ``(onapdocs)``.
 .. code-block:: bash
 
    pip3 install wheel
 .. code-block:: bash
 
    pip3 install wheel
-   pip3 install sphinx_rtd_theme
-   pip3 install sphinxcontrib-blockdiag
-   pip3 install sphinxcontrib-needs
-   pip3 install sphinxcontrib-nwdiag
-   pip3 install sphinxcontrib-seqdiag
-   pip3 install sphinxcontrib-swaggerdoc
-   pip3 install sphinxcontrib-plantuml
    pip3 install lfdocs-conf
 
    which sphinx-build
 
    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.
 .. tip:: Remember the path
    ``/home/<USER>/environments/onapdocs/bin/sphinx-build``, you need it later
    to configure a VSC extension.
@@ -313,16 +313,16 @@ desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
 the bottom left corner) to find the required applications.
 
 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
 the bottom left corner) to find the required applications.
 
 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
-:guilabel:`Visual Studio Code` and press :guilabel:`Install` to install the
-integrated development environment (IDE).
+:guilabel:`code` (Visual Studio Code) and press :guilabel:`Install` to install
+the integrated development environment (IDE).
 
 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
 installed applications are up to date.
 
 -------------------------------------------------------------------------------
 
 
 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
 installed applications are up to date.
 
 -------------------------------------------------------------------------------
 
-Clone example repo and start VSC (no LF account)
-================================================
+Clone example repo (no LF account)
+==================================
 
 Clone repo
 ----------
 
 Clone repo
 ----------
@@ -335,23 +335,10 @@ Linux Foundation (LF) account with ...
    cd ~/environments/onapdocs
    git clone --branch master https://git.onap.org/doc/ ./doc
 
    cd ~/environments/onapdocs
    git clone --branch master https://git.onap.org/doc/ ./doc
 
-Start VSC
----------
-
-Start VSC in the ``doc`` repo directory with ...
-
-.. code-block:: bash
-
-   cd doc
-   code .
-
-.. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}``
-   because you have started VSC (``code``) from here!
-
 -------------------------------------------------------------------------------
 
 -------------------------------------------------------------------------------
 
-Clone example repo and start VSC (LF account used)
-==================================================
+Clone example repo (LF account used)
+====================================
 
 Prerequisite configuration
 --------------------------
 
 Prerequisite configuration
 --------------------------
@@ -385,18 +372,24 @@ Clone repo
    cd ~/environments/onapdocs
    git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
 
    cd ~/environments/onapdocs
    git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
 
-Start VSC
----------
+-------------------------------------------------------------------------------
 
 
-Start VSC in the ``doc`` repo directory with ...
+Start VSC in the correct directory
+==================================
+
+Start VSC (always) in the ``docs`` directory of your repository. For the
+``doc`` repository used in this example do this with ...
 
 .. code-block:: bash
 
    cd doc
 
 .. code-block:: bash
 
    cd doc
+   cd docs
    code .
 
    code .
 
-.. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}``
-   because you have started VSC (``code``) from here!
+.. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
+
+.. tip:: ``~/environments/onapdocs/doc/docs`` is now your
+   ``${workspaceFolder}`` because you have started VSC (``code .``) from here!
 
 -------------------------------------------------------------------------------
 
 
 -------------------------------------------------------------------------------
 
@@ -431,17 +424,17 @@ Press :guilabel:`Install` if you have found the required extension.
 
 Please install ...
 
 
 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
 ------------------------------------
 
 Configure reStructuredText extension
 ------------------------------------
@@ -472,6 +465,8 @@ Only in case the preview creates an error message, try ...
 
 Close the :guilabel:`Extension Settings` window.
 
 
 Close the :guilabel:`Extension Settings` window.
 
+Close VSC and start it again with the ``code .`` command.
+
 -------------------------------------------------------------------------------
 
 Open a .rst file and preview it in VSC
 -------------------------------------------------------------------------------
 
 Open a .rst file and preview it in VSC
@@ -480,10 +475,14 @@ Open a .rst file and preview it in VSC
 Open .rst file
 --------------
 
 Open .rst file
 --------------
 
-Select :guilabel:`View` > :guilabel:`Explorer`. Alternatively you can use the
-|FileExpl| symbol in the upper left corner. Expand the ``docs`` folder by
-clicking on the ``>`` symbol. Select the file ``index.rst``. The code shows up
-in the right pane window of VSC.
+Select :guilabel:`View` > :guilabel:`Explorer`. Or use the |FileExpl| symbol in
+the upper left corner. Expand the ``docs`` folder by clicking on the ``>``
+symbol. Select the file ``index.rst``. The code shows up in the right pane
+window of VSC.
+
+Alternatively you can open this guide and see how it looks like in the
+reStructuredText format. It can be found in ``docs/guides/onap-documentation``
+and is named ``setup-of-a-doc-dev-system.rst``.
 
 Problem Window
 --------------
 
 Problem Window
 --------------
@@ -543,8 +542,8 @@ your system first.
 Optional VSC Configuration
 ==========================
 
 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
 
 To add a ruler that indicates the line end at 79 characters, open
 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
@@ -558,6 +557,15 @@ the value ``79``. The result should look like this:
         79
     ]
 
         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
 -------------------------------------------------------------------------------
 
 Miscellaneous
@@ -572,13 +580,13 @@ Firefox Add-ons
 Open :guilabel:`Add-Ons and Themes`, then search and install the following
 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
 -------------
 
 ReText Editor
 -------------
@@ -597,6 +605,16 @@ Helpful Resources
 This is a collection of helpful resources if you want to extend and deepen your
 knowledge.
 
 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
 ------
 
 Python
 ------
 
@@ -606,6 +624,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/>`__
 
 - `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
 ----------------
 
 reStructuredText
 ----------------
 
@@ -614,11 +638,15 @@ 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/#>`__
 
 - `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
-------------------------
+Sphinx
+------
 
 
-- `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>`__
+- `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
+
+Ubuntu
+------
+
+- `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
 
 Visual Studio Code (VSC)
 ------------------------
 
 Visual Studio Code (VSC)
 ------------------------
@@ -627,16 +655,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>`__
 
 - `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
 -------------------------------------------------------------------------------
 
 Backlog
Create and maintain documentation targeted to ONAP user audiences