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