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

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2021 Deutsche Telekom AG
   4
   5
   6
   7 *******************************************
   8 Setup of a Documentation Development System
   9 *******************************************
  10
  11
  12 ..
  13    #########################################################################
  14    HOW TO FILL THIS SECTION:
  15
  16    Release Relevance
  17       Name the ONAP release(s) where this document has a relevance.
  18       ONAP release number (ONAP release name starting with a capital letter)
  19       Examples:
  20       8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
  21       7.0.1 (Guilin) - 3.0.0 (Casablanca), 1.0.0 (Amsterdam)
  22
  23    Last Review/Update
  24       Date of last review and/or update of this document.
  25       Add "none" for a new document. Add concrete date if reviewed/updated.
  26       Use en-US format (mm/dd/yyyy).
  27
  28    Initial Release
  29       Initial release date of this document.
  30       Use en-US format (mm/dd/yyyy).
  31
  32    Author (Company)
  33       Name of the author and company name. Use comma to separate.
  34       Example:
  35       Jane Doe (ACME), John Doe (ACME)
  36
  37    ! PLEASE DO NOT CHANGE THE STRUCTURE OF THIS SECTION.
  38    ! PLEASE ADD ONLY REQUESTED INFORMATION BELOW!
  39    #########################################################################
  40
  41 Release Relevance
  42    8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
  43
  44 Last Review/Update
  45    06/17/2021
  46
  47 Initial Release
  48    05/12/2021
  49
  50 Author (Company)
  51    Thomas Kulik (Deutsche Telekom AG)
  52
  53 -------------------------------------------------------------------------------
  54
  55 .. contents:: Table of Contents
  56
  57 -------------------------------------------------------------------------------
  58
  59 Introduction
  60 ============
  61
  62 This guide provides a detailed description to set up a system suitable to
  63 create, check and preview documentation locally. The targeted readership are
  64 beginners and people interested in creating documentation.
  65
  66 The guide describes the setup of a development system from scratch using the
  67 Ubuntu Desktop version installed in a virtual machine. It includes all required
  68 steps and also some optional ones that may ease your daily work with this
  69 development system. Feel free to adapt it to your needs.
  70
  71 In general, formal ONAP documentation uses the reStructuredText markup language
  72 and the files have an ``.rst`` extension. They are part of almost every ONAP
  73 project and can be found in the ``docs`` directory. The files are automatically
  74 processed and you find the final ONAP documentation build hosted on
  75 `ReadTheDocs <https://docs.onap.org>`__.
  76
  77 -------------------------------------------------------------------------------
  78
  79 VM Configuration
  80 ================
  81
  82 .. note:: This section is for information only and should not be understood as
  83           a requirement.
  84
  85 Ubuntu Image
  86 ------------
  87
  88 +----------------------------------------+
  89 | ubuntu-20.04.2.0-desktop-amd64.iso     |
  90 +----------------------------------------+
  91
  92 Please check what image must be used for your type of hardware.
  93
  94 VM Configuration
  95 ----------------
  96
  97 +-------------------------+------------+
  98 | Memory                  | 8 GB       |
  99 +-------------------------+------------+
 100 | Processors / Cores each | 2 / 2      |
 101 +-------------------------+------------+
 102 | Hard Disk               | 64 GB      |
 103 +-------------------------+------------+
 104
 105 Depending on your requirements you can modify the values for virtual memory,
 106 processors, cores or hard disk space.
 107
 108 VM Setup
 109 --------
 110
 111 Follow the instructions of your virtualization solution to install Ubuntu in a
 112 virtual machine. Log in after the installation has finished.
 113
 114 -------------------------------------------------------------------------------
 115
 116 Ubuntu Configuration
 117 ====================
 118
 119 .. note:: This section is optional and should not be understood as a
 120    requirement.
 121
 122 Finding Applications
 123 --------------------
 124
 125 The following actions are performed on the Ubuntu desktop. You may use the
 126 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
 127 the bottom left corner) to find the required applications. Later on you need to
 128 start also a :guilabel:`Terminal` window from here.
 129
 130 Software Updates
 131 ----------------
 132
 133 Open :guilabel:`Software Updater` and update already installed Ubuntu packages.
 134 You may need to restart the system afterwards.
 135
 136 Language Support
 137 ----------------
 138
 139 Open :guilabel:`Language Support`. You are asked to complete the installation.
 140 Select the :guilabel:`Install` button to complete. Continue in the
 141 :guilabel:`Language Support` window and open
 142 :guilabel:`Install / Remove Languages`. Then select your preferred
 143 :guilabel:`<LANGUAGE>`. Choose :guilabel:`Apply` to install the additional
 144 language.
 145
 146 Regional Formats
 147 ----------------
 148
 149 Continue to the :guilabel:`Regional Formats` tab. Select a
 150 :guilabel:`<FORMAT>` to show e.g. date, time and numbers in your preferred
 151 format. Press :guilabel:`Close` to close the window.
 152
 153 Input Sources
 154 -------------
 155
 156 To change the keyboard layout used e.g. in command line windows, open
 157 :guilabel:`Settings`. Navigate to :guilabel:`Region & Language`. At
 158 :guilabel:`Input Sources` press the :guilabel:`+` sign. Select your preferred
 159 :guilabel:`<INPUTSOURCE>` and use :guilabel:`Add` to add it. Move it to the top
 160 of the list using drag and drop. Close the window. You may need to logout from
 161 the UI and login again to make your changes effective.
 162
 163 Screen Lock
 164 -----------
 165
 166 Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
 167 :guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
 168 and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
 169 window.
 170
 171 -------------------------------------------------------------------------------
 172
 173 Disable sudo password for your user
 174 ===================================
 175
 176 .. warning:: This section is optional and should not be understood as a
 177    requirement. Disabling password authentication for all commands is very
 178    convenient at use **but it strongly exposes your system to malicious code**.
 179    For a system dedicated to development it might be OK, but not for a
 180    production system! Handle with care. You have been warned.
 181
 182 Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ...
 183
 184 .. code-block:: bash
 185
 186    sudo visudo
 187
 188 and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
 189 ``<USER>`` with your user name.
 190
 191 -------------------------------------------------------------------------------
 192
 193 Install python3 related packages
 194 ================================
 195
 196 .. note:: The main python3 package is preinstalled in Ubuntu 20.04.
 197
 198 Open a :guilabel:`Terminal` window and update the package management system
 199 with ...
 200
 201 .. code-block:: bash
 202
 203    cd ~
 204    sudo apt update
 205    sudo apt -y upgrade
 206
 207 Install python3 related packages with ...
 208
 209 .. code-block:: bash
 210
 211    sudo apt install -y python3-pip
 212    sudo apt install -y build-essential
 213    sudo apt install -y libssl-dev
 214    sudo apt install -y libffi-dev
 215    sudo apt install -y python3-dev
 216    sudo apt install -y python3-venv
 217
 218
 219 Check the python3 version with ...
 220
 221 .. code-block:: bash
 222
 223    python3 -V
 224
 225 -------------------------------------------------------------------------------
 226
 227 Install git and documentation related packages
 228 ==============================================
 229
 230 Install the required packages with ...
 231
 232 .. code-block:: bash
 233
 234    sudo apt install -y git
 235    sudo apt install -y git-review
 236    sudo apt install -y python3-sphinx
 237    sudo apt install -y python3-doc8
 238    sudo apt install -y curl
 239    sudo apt install -y jq
 240
 241 Check the git version with ...
 242
 243 .. code-block:: bash
 244
 245    git --version
 246
 247 -------------------------------------------------------------------------------
 248
 249 Create virtual environment and activate
 250 =======================================
 251
 252 In this guide, virtual environments are generally located in your home
 253 directory under ``~/environments``. For the development of ONAP documentation
 254 the virtual environment ``onapdocs`` is created. The full path is consequently
 255 ``~/environments/onapdocs``.
 256
 257 .. code-block:: bash
 258
 259    cd ~
 260    mkdir environments
 261    cd ~/environments
 262    python3 -m venv onapdocs
 263    cd ~/environments/onapdocs
 264    source bin/activate
 265
 266 To indicate that you are now working in an virtual environment, the prompt of
 267 your terminal has changed. Now it starts with ``(onapdocs)``.
 268
 269 -------------------------------------------------------------------------------
 270
 271 Install required Sphinx packages in activated environment
 272 =========================================================
 273
 274 It is :strong:`important` to activate the ``onapdocs`` environment before you
 275 continue. If not already done, activate environment with ...
 276
 277 .. code-block:: bash
 278
 279    cd ~/environments/onapdocs
 280    source bin/activate
 281
 282 To indicate that you are now working in an virtual environment, the prompt of
 283 your terminal has changed. Now it starts with ``(onapdocs)``.
 284
 285 .. important:: Now you are installing packages only for the 'onapdocs' virtual
 286    environment.
 287
 288 .. code-block:: bash
 289
 290    pip3 install wheel
 291    pip3 install sphinx_rtd_theme
 292    pip3 install sphinxcontrib-blockdiag
 293    pip3 install sphinxcontrib-needs
 294    pip3 install sphinxcontrib-nwdiag
 295    pip3 install sphinxcontrib-seqdiag
 296    pip3 install sphinxcontrib-swaggerdoc
 297    pip3 install sphinxcontrib-plantuml
 298    pip3 install lfdocs-conf
 299    pip3 install pylint
 300
 301    which sphinx-build
 302
 303 .. tip:: Remember the path
 304    ``/home/<USER>/environments/onapdocs/bin/sphinx-build``, you need it later
 305    to configure a VSC extension.
 306
 307 -------------------------------------------------------------------------------
 308
 309 Install Visual Studio Code (VSC) and update already installed applications
 310 ==========================================================================
 311
 312 The following actions are performed on the Ubuntu desktop. You may use the
 313 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
 314 the bottom left corner) to find the required applications.
 315
 316 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
 317 :guilabel:`Visual Studio Code` and press :guilabel:`Install` to install the
 318 integrated development environment (IDE).
 319
 320 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
 321 installed applications are up to date.
 322
 323 -------------------------------------------------------------------------------
 324
 325 Clone example repo (no LF account)
 326 ==================================
 327
 328 Clone repo
 329 ----------
 330
 331 For a quick start you can clone e.g. the ``doc`` repository even without a
 332 Linux Foundation (LF) account with ...
 333
 334 .. code-block:: bash
 335
 336    cd ~/environments/onapdocs
 337    git clone --branch master https://git.onap.org/doc/ ./doc
 338
 339 -------------------------------------------------------------------------------
 340
 341 Clone example repo (LF account used)
 342 ====================================
 343
 344 Prerequisite configuration
 345 --------------------------
 346
 347 If you plan to contribute to the ONAP community and you want to submit changes
 348 to a specific project later on, please refer to the
 349 `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information about all
 350 the prerequisite details.
 351
 352 If you already have a LF account and you have shared your public ssh key you
 353 can finalize the configuration of this development system by updating your ssh
 354 configuration in the ``~/.ssh`` directory by copying over ``config``,
 355 ``id_rsa`` and ``id_rsa.pub``
 356
 357 In addition you configure ``git`` and ``git-review`` with ...
 358
 359 .. code-block:: bash
 360
 361    git config --global user.email "<GIT-EMAIL>"
 362    git config --global user.name "<GIT-USER>"
 363    git config --global --add gitreview.username "<GIT-USER>"
 364    git config --global gitreview.remote origin
 365
 366 Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
 367
 368 Clone repo
 369 ----------
 370
 371 .. code-block:: bash
 372
 373    cd ~/environments/onapdocs
 374    git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
 375
 376 -------------------------------------------------------------------------------
 377
 378 Start VSC in the correct directory
 379 ==================================
 380
 381 Start VSC (always) in the ``docs`` directory of your repository. For the
 382 ``doc`` repository used in this example do this with ...
 383
 384 .. code-block:: bash
 385
 386    cd doc
 387    cd docs
 388    code .
 389
 390 .. tip:: ``~/environments/onapdocs/doc/docs`` is now your
 391    ``${workspaceFolder}`` because you have started VSC (``code .``) from here!
 392
 393 -------------------------------------------------------------------------------
 394
 395 Disable Telemetry of VSC
 396 ========================
 397
 398 In case you want to disable telemetry functionality of Visual Studio Code, open
 399 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
 400 search for ``telemetry``. Then uncheck
 401 :guilabel:`Telemetry: Enable Crash Reporter` and
 402 :guilabel:`Telemetry: Enable Telemetry`
 403
 404 .. warning:: Extensions may be collecting their own usage data and are not
 405    controlled by the ``telemetry.enableTelemetry`` setting. Consult the
 406    specific extension's documentation to learn about its telemetry
 407    reporting and whether it can be disabled. See also
 408    https://code.visualstudio.com/docs/getstarted/telemetry
 409
 410 -------------------------------------------------------------------------------
 411
 412 Install VSC extensions and configure reStructuredText extension
 413 ===============================================================
 414
 415 Install VSC extensions
 416 ----------------------
 417
 418 Extension bring additional power to Visual Studio Code. To search and install
 419 them, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Extensions`
 420 or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the
 421 extension in the :guilabel:`Search Extensions in Marketplace` window.
 422 Press :guilabel:`Install` if you have found the required extension.
 423
 424 Please install ...
 425
 426 +-----------------------+-----------------------------------------+
 427 | Python                | ms-python.python                        |
 428 +-----------------------+-----------------------------------------+
 429 | reStructuredText      | lextudio.restructuredtext               |
 430 +-----------------------+-----------------------------------------+
 431 | Code Spell Checker    | streetsidesoftware.code-spell-checker   |
 432 +-----------------------+-----------------------------------------+
 433 | Prettier              | esbenp.prettier-vscode                  |
 434 +-----------------------+-----------------------------------------+
 435 | GitLens               | eamodio.gitlens                         |
 436 +-----------------------+-----------------------------------------+
 437
 438 Configure reStructuredText extension
 439 ------------------------------------
 440
 441 To configure ``reStructuredText`` extension, open :guilabel:`File` >
 442 :guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut
 443 ``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the
 444 :guilabel:`Search Extensions in Marketplace` window. After you have found the
 445 extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
 446 bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
 447 all the parameters. Change the following ones:
 448
 449  :strong:`Restructuredtext › Linter: Executable Path`
 450   ``/usr/bin/doc8``
 451
 452  :strong:`Restructuredtext › Linter: Name`
 453   ``doc8``
 454
 455  :strong:`Restructuredtext: Sphinx Build Path`
 456   ``/home/<USER>/environments/onapdocs/bin/sphinx-build``
 457
 458 Replace ``<USER>`` with your user name.
 459
 460 Only in case the preview creates an error message, try ...
 461
 462   :strong:`Restructuredtext: Conf Path`
 463    ``${workspaceFolder}/docs``
 464
 465 Close the :guilabel:`Extension Settings` window.
 466
 467 -------------------------------------------------------------------------------
 468
 469 Open a .rst file and preview it in VSC
 470 ======================================
 471
 472 Open .rst file
 473 --------------
 474
 475 Select :guilabel:`View` > :guilabel:`Explorer`. Or use the |FileExpl| symbol in
 476 the upper left corner. Expand the ``docs`` folder by clicking on the ``>``
 477 symbol. Select the file ``index.rst``. The code shows up in the right pane
 478 window of VSC.
 479
 480 Alternatively you can open this guide and see how it looks like in the
 481 reStructuredText format. It can be found in ``docs/guides/onap-documentation``
 482 and is named ``setup-of-a-doc-dev-system.rst``.
 483
 484 Problem Window
 485 --------------
 486
 487 You may see problems with the reStructuredText markup because the code is
 488 underlined in various colors. For the details select :guilabel:`View` >
 489 :guilabel:`Problems` to open an additional window at the bottom of VSC.
 490
 491 When you select a specific entry in the problem list, the code window is
 492 updated to show the related line in the code.
 493
 494 Preview
 495 -------
 496
 497 Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top
 498 right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window
 499 on the right hand side. This may take a few seconds. The preview shows up and
 500 renders the ``index.rst`` as it would look like on ReadTheDocs.
 501
 502 Tips and Tricks
 503 ---------------
 504
 505 The learnings are ...
 506
 507 .. tip::
 508    - Start VSC always in the ``docs`` directory of the repository. Use the
 509      command ``code .``. Then navigate via VSC's :guilabel:`Explorer`
 510      |FileExpl| to the directory which contains the file you like to edit. VSC
 511      may ask you, which ``conf.py`` VSC should use. Choose the one which
 512      resides in the directory where you have started VSC. Check also the (blue)
 513      bottom line of VSC. There you see which ``conf.py`` is currently in use.
 514      The content of ``conf.py`` affects how the documentation is presented.
 515    - VSC may claim that some packages require an update. This can be easily
 516      fixed. VSC offers automatically to install or update the package.
 517    - VSC may ask you to install ``snooty``. Please install.
 518    - Select the correct environment in the (blue) bottom line
 519      ``'onapdocs':venv``. Have also a view on the other interesting
 520      information (e.g. the ``conf.py`` which is currently in use).
 521    - First, close and reopen preview if preview is not shown properly.
 522    - Second, close and reopen VSC if preview is not shown properly.
 523    - Save your file if an error does not disappear after you have corrected it.
 524    - You can not navigate within the document structure by clicking the links
 525      in the preview. You always have to choose the correct file in the VSC
 526      :guilabel:`Explorer` window.
 527
 528 That's it!
 529 ----------
 530
 531 Congratulations, well done! You have configured a system well suited to
 532 develop ONAP documentation and to master the challenges of reStructuredText.
 533 Now have a look at all the different elements of reStructuredText and learn how
 534 to use them properly. Or maybe you like to do some optional configurations at
 535 your system first.
 536
 537 -------------------------------------------------------------------------------
 538
 539 Optional VSC Configuration
 540 ==========================
 541
 542 Add Ruler
 543 ---------
 544
 545 To add a ruler that indicates the line end at 79 characters, open
 546 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
 547 ``ruler`` in the :guilabel:`Search settings` field. In
 548 :guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add
 549 the value ``79``. The result should look like this:
 550
 551 .. code-block:: bash
 552
 553     "editor.rulers": [
 554         79
 555     ]
 556
 557 Disable Synchronized Scrolling of Editor and Preview
 558 ----------------------------------------------------
 559
 560 To disable the synchronized scrolling of editor and preview, open
 561 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
 562 search for ``Restructuredtext › Preview: Scroll``. Then uncheck
 563 :guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
 564 :guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
 565
 566 -------------------------------------------------------------------------------
 567
 568 Miscellaneous
 569 =============
 570
 571 .. note:: This section is optional and should not be understood as a
 572    requirement.
 573
 574 Firefox Add-ons
 575 ---------------
 576
 577 Open :guilabel:`Add-Ons and Themes`, then search and install the following
 578 add-ons:
 579
 580 +------------------------------+-------------------------------+
 581 | I don't care about cookies   | Get rid of cookie warnings.   |
 582 +------------------------------+-------------------------------+
 583 | UBlock Origin                | A wide-spectrum blocker.      |
 584 +------------------------------+-------------------------------+
 585 | LastPass Password Manager    | Used in the Linux Foundation. |
 586 +------------------------------+-------------------------------+
 587
 588 ReText Editor
 589 -------------
 590
 591 Install this simple editor with ...
 592
 593 .. code-block:: bash
 594
 595    sudo apt install -y retext
 596
 597 -------------------------------------------------------------------------------
 598
 599 Helpful Resources
 600 =================
 601
 602 This is a collection of helpful resources if you want to extend and deepen your
 603 knowledge.
 604
 605 Documentation
 606 -------------
 607
 608 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
 609
 610 Git
 611 ---
 612
 613 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
 614
 615 Python
 616 ------
 617
 618 - `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__
 619 - `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>`__
 620 - `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__
 621 - `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
 622 - `Linux Foundation Docs Conf <https://pypi.org/project/lfdocs-conf/>`__
 623
 624 ReadTheDocs Sphinx Theme
 625 ------------------------
 626
 627 - `ReadTheDocs Sphinx Theme (Recommended Reading!) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
 628 - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
 629
 630 reStructuredText
 631 ----------------
 632
 633 - `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__
 634 - `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
 635 - `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
 636 - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
 637
 638 Sphinx
 639 ------
 640
 641 - `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
 642
 643 Ubuntu
 644 ------
 645
 646 - `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
 647
 648 Visual Studio Code (VSC)
 649 ------------------------
 650
 651 - `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__
 652 - `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
 653 - `VSC Icons <https://github.com/microsoft/vscode-icons>`__
 654
 655 -------------------------------------------------------------------------------
 656
 657 Backlog
 658 =======
 659
 660 There are still some open topics or issues in this guide. They are subject
 661 for one of the upcoming releases.
 662
 663  - consider ``pandoc`` in this guide?
 664  - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build
 665    Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives?
 666  - link to full ``ssh`` install/config?
 667  - link to full ``git`` install/config?
 668  - how to limit line width to improve readability? setting in conf.py?
 669  - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
 670    :kbd:`X` Is this a problem in the RTD theme?
 671  - use ``menuselection``
 672    :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
 673  - evaluate and add VSC extension to "draw" tables in an aided way
 674  - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
 675  - find the reason for VSC error message
 676    ``Substitution definition "ShowApp" empty or invalid.``
 677  - find the reason for VSC error message
 678    ``Unexpected indentation``
 679  - find a solution to wrap lines in VSC automatically (79 chars limit)
 680  - evaluate ``snooty`` and describe functionality (build in? not a extension?)
 681  - add a table explaining the role of installed packages/extensions in every
 682    section
 683
 684 ..
 685    #########################################################################
 686    EMBEDDED PICTURES & ICONS BELOW
 687    #########################################################################
 688
 689 .. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
 690    :width: 20
 691
 692 .. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
 693    :width: 20
 694
 695 .. |FileExpl| image:: ./media/files.svg
 696    :width: 20
 697
 698 .. |GearSymb| image:: ./media/gear.svg
 699    :width: 20