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    11.x.x (Kohn) - 10.x.x (Jakarta)
  43
  44 Last Review/Update
  45    2022/09/01
  46
  47 Initial Release
  48    2021/12/05
  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                        build-essential \
 217                        libssl-dev \
 218                        libffi-dev \
 219                        python3-dev \
 220                        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                        git-review \
 240                        python3-sphinx \
 241                        python3-doc8 \
 242                        curl \
 243                        jq \
 244                        tox
 245
 246 Check the git version and the path of the sphinx-build executable ...
 247
 248 .. code-block:: bash
 249
 250    git --version
 251
 252    which sphinx-build
 253
 254
 255 .. tip:: Remember the path
 256    ``/usr/bin/sphinx-build``, you need it later
 257    to configure a VSC extension.
 258
 259 -------------------------------------------------------------------------------
 260
 261 Create virtual environment and activate
 262 =======================================
 263
 264 In this guide, virtual environments are generally located in your home
 265 directory under ``~/environments``. For the development of ONAP documentation
 266 the virtual environment ``onapdocs`` is created. The full path is consequently
 267 ``~/environments/onapdocs``.
 268
 269 .. code-block:: bash
 270
 271    cd ~
 272    mkdir environments
 273    cd ~/environments
 274    python3 -m venv onapdocs
 275    cd ~/environments/onapdocs
 276    source bin/activate
 277
 278 To indicate that you are now working in an virtual environment, the prompt of
 279 your terminal has changed. Now it starts with ``(onapdocs)``.
 280
 281 -------------------------------------------------------------------------------
 282
 283 Install required Sphinx packages in activated environment (I)
 284 =============================================================
 285
 286 It is :strong:`important` to activate the ``onapdocs`` environment before you
 287 continue. If not already done, activate environment with ...
 288
 289 .. code-block:: bash
 290
 291    cd ~/environments/onapdocs
 292    source bin/activate
 293
 294 To indicate that you are now working in an virtual environment, the prompt of
 295 your terminal has changed. Now it starts with ``(onapdocs)``.
 296
 297 .. important:: Now you are installing packages only for the 'onapdocs' virtual
 298    environment.
 299
 300 .. code-block:: bash
 301
 302    pip3 install wheel
 303
 304 -------------------------------------------------------------------------------
 305
 306 Install Visual Studio Code (VSC) and update already installed applications
 307 ==========================================================================
 308
 309 The following actions are performed on the Ubuntu desktop. You may use the
 310 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
 311 the bottom left corner) to find the required applications.
 312
 313 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
 314 :guilabel:`code` (Visual Studio Code) and press :guilabel:`Install` to install
 315 the integrated development environment (IDE).
 316
 317 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
 318 installed applications are up to date.
 319
 320 -------------------------------------------------------------------------------
 321
 322 Clone example repo (no LF account)
 323 ==================================
 324
 325 Clone repo
 326 ----------
 327
 328 For a quick start you can clone e.g. the ``doc`` repository even without a
 329 Linux Foundation (LF) account with ...
 330
 331 .. code-block:: bash
 332
 333    cd ~/environments/onapdocs
 334    git clone --branch master https://git.onap.org/doc/ ./doc
 335
 336 -------------------------------------------------------------------------------
 337
 338 Clone example repo (LF account used)
 339 ====================================
 340
 341 Prerequisite configuration
 342 --------------------------
 343
 344 If you plan to contribute to the ONAP community and you want to submit changes
 345 to a specific project later on, please refer to the
 346 `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information about all
 347 the prerequisite details.
 348
 349 If you already have a LF account and you have shared your public ssh key you
 350 can finalize the configuration of this development system by updating your ssh
 351 configuration in the ``~/.ssh`` directory by copying over ``config``,
 352 ``id_rsa`` and ``id_rsa.pub``
 353
 354 In addition you configure ``git`` and ``git-review`` with ...
 355
 356 .. code-block:: bash
 357
 358    git config --global user.email "<GIT-EMAIL>"
 359    git config --global user.name "<GIT-USER>"
 360    git config --global --add gitreview.username "<GIT-USER>"
 361    git config --global gitreview.remote origin
 362
 363 Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
 364
 365 Clone repo
 366 ----------
 367
 368 .. code-block:: bash
 369
 370    cd ~/environments/onapdocs
 371    git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
 372
 373 -------------------------------------------------------------------------------
 374
 375 Install required Sphinx packages in activated environment (II)
 376 ==============================================================
 377
 378 Continue with the installation of required packages. Use the file
 379 ``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
 380 repository.
 381
 382 .. code-block:: bash
 383
 384    cd ~/environments/onapdocs
 385    sudo pip install -r doc/etc/requirements-docs.txt
 386
 387 -------------------------------------------------------------------------------
 388
 389 Start VSC in the correct directory
 390 ==================================
 391
 392 Start VSC (always) in the ``docs`` directory of your repository. For the
 393 ``doc`` repository used in this example do this with ...
 394
 395 .. code-block:: bash
 396
 397    cd doc
 398    cd docs
 399    code .
 400
 401 .. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
 402
 403 .. tip:: ``~/environments/onapdocs/doc/docs`` is now your
 404    ``${workspaceFolder}`` because you have started VSC (``code .``) from here!
 405
 406 -------------------------------------------------------------------------------
 407
 408 Disable Telemetry of VSC
 409 ========================
 410
 411 In case you want to disable telemetry functionality of Visual Studio Code, open
 412 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Telemetry Settings` and
 413 turn it ``off`` in the selection field.
 414
 415 In an older version of VSC you alternatively need to open
 416 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
 417 search for ``telemetry``. Then uncheck
 418 :guilabel:`Telemetry: Enable Crash Reporter` and
 419 :guilabel:`Telemetry: Enable Telemetry`
 420
 421 .. warning:: Extensions may be collecting their own usage data and are not
 422    controlled by the ``telemetry.enableTelemetry`` setting. Consult the
 423    specific extension's documentation to learn about its telemetry
 424    reporting and whether it can be disabled. See also
 425    https://code.visualstudio.com/docs/getstarted/telemetry
 426
 427 -------------------------------------------------------------------------------
 428
 429 Install VSC extensions and configure reStructuredText extension
 430 ===============================================================
 431
 432 Install VSC extensions
 433 ----------------------
 434
 435 Extension bring additional power to Visual Studio Code. To search and install
 436 them, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Extensions`
 437 or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the
 438 extension in the :guilabel:`Search Extensions in Marketplace` window.
 439 Press :guilabel:`Install` if you have found the required extension.
 440
 441 Please install ...
 442
 443 +--------------------------------------+---------------------------------------+---------+
 444 | Python                               | ms-python.python                      | latest  |
 445 +--------------------------------------+---------------------------------------+---------+
 446 | reStructuredText                     | lextudio.restructuredtext             | 169.0.0 |
 447 +--------------------------------------+---------------------------------------+---------+
 448 | reStructuredText Syntax highlighting | trond-snekvik.simple-rst              | latest  |
 449 +--------------------------------------+---------------------------------------+---------+
 450 | Code Spell Checker                   | streetsidesoftware.code-spell-checker | latest  |
 451 +--------------------------------------+---------------------------------------+---------+
 452 | Prettier                             | esbenp.prettier-vscode                | latest  |
 453 +--------------------------------------+---------------------------------------+---------+
 454 | GitLens                              | eamodio.gitlens                       | latest  |
 455 +--------------------------------------+---------------------------------------+---------+
 456
 457 .. warning:: Use the reStructuredText extension version 169.0.0 or lower to
 458    avoid problems with the preview. You need to downgrade after the initial
 459    installation. This can be done by using
 460    :guilabel:`Uninstall` > :guilabel:`Install Another Version...` in the VSC
 461    extension management.
 462
 463 Configure reStructuredText extension
 464 ------------------------------------
 465
 466 To configure ``reStructuredText`` extension, open :guilabel:`File` >
 467 :guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut
 468 ``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the
 469 :guilabel:`Search Extensions in Marketplace` window. After you have found the
 470 extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
 471 bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
 472 all the parameters. Change the following ones:
 473
 474  :strong:`Restructuredtext › Linter: Executable Path`
 475   ``/usr/bin/doc8``
 476
 477  :strong:`Restructuredtext › Linter: Name`
 478   ``doc8``
 479
 480  :strong:`Restructuredtext: Sphinx Build Path`
 481   ``/usr/bin/sphinx-build``
 482
 483 Replace ``<USER>`` with your user name.
 484
 485 Only in case the preview creates an error message, try ...
 486
 487   :strong:`Restructuredtext: Conf Path`
 488    ``${workspaceFolder}/docs``
 489
 490 Close the :guilabel:`Extension Settings` window.
 491
 492 Close VSC and start it again with the ``code .`` command.
 493
 494 -------------------------------------------------------------------------------
 495
 496 Open a .rst file and preview it in VSC
 497 ======================================
 498
 499 Open .rst file
 500 --------------
 501
 502 Select :guilabel:`View` > :guilabel:`Explorer`. Or use the |FileExpl| symbol in
 503 the upper left corner. Expand the ``docs`` folder by clicking on the ``>``
 504 symbol. Select the file ``index.rst``. The code shows up in the right pane
 505 window of VSC.
 506
 507 Alternatively you can open this guide and see how it looks like in the
 508 reStructuredText format. It can be found in ``docs/guides/onap-documentation``
 509 and is named ``setup-of-a-doc-dev-system.rst``.
 510
 511 Problem Window
 512 --------------
 513
 514 You may see problems with the reStructuredText markup because the code is
 515 underlined in various colors. For the details select :guilabel:`View` >
 516 :guilabel:`Problems` to open an additional window at the bottom of VSC.
 517
 518 When you select a specific entry in the problem list, the code window is
 519 updated to show the related line in the code.
 520
 521 Preview
 522 -------
 523
 524 Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top
 525 right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window
 526 on the right hand side. This may take a few seconds. The preview shows up and
 527 renders the ``index.rst`` as it would look like on ReadTheDocs.
 528
 529 Tips and Tricks
 530 ---------------
 531
 532 The learnings are ...
 533
 534 .. tip::
 535    - Start VSC always in the ``docs`` directory of the repository. Use the
 536      command ``code .``. Then navigate via VSC's :guilabel:`Explorer`
 537      |FileExpl| to the directory which contains the file you like to edit. VSC
 538      may ask you, which ``conf.py`` VSC should use. Choose the one which
 539      resides in the directory where you have started VSC. Check also the (blue)
 540      bottom line of VSC. There you see which ``conf.py`` is currently in use.
 541      The content of ``conf.py`` affects how the documentation is presented.
 542    - VSC may claim that some packages require an update. This can be easily
 543      fixed. VSC offers automatically to install or update the package.
 544    - VSC may ask you to install ``snooty``. Please install.
 545    - Select the correct environment in the (blue) bottom line
 546      ``'onapdocs':venv``. Have also a view on the other interesting
 547      information (e.g. the ``conf.py`` which is currently in use).
 548    - First, close and reopen preview if preview is not shown properly.
 549    - Second, close and reopen VSC if preview is not shown properly.
 550    - Save your file if an error does not disappear after you have corrected it.
 551    - You can not navigate within the document structure by clicking the links
 552      in the preview. You always have to choose the correct file in the VSC
 553      :guilabel:`Explorer` window.
 554
 555 That's it!
 556 ----------
 557
 558 Congratulations, well done! You have configured a system well suited to
 559 develop ONAP documentation and to master the challenges of reStructuredText.
 560 Now have a look at all the different elements of reStructuredText and learn how
 561 to use them properly. Or maybe you like to do some optional configurations at
 562 your system first.
 563
 564 -------------------------------------------------------------------------------
 565
 566 Optional VSC Configuration
 567 ==========================
 568
 569 Add Ruler
 570 ---------
 571
 572 To add a ruler that indicates the line end at 79 characters, open
 573 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
 574 ``ruler`` in the :guilabel:`Search settings` field. In
 575 :guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add
 576 the value ``79``. The result should look like this:
 577
 578 .. code-block:: bash
 579
 580     "editor.rulers": [
 581         79
 582     ]
 583
 584 Disable Synchronized Scrolling of Editor and Preview
 585 ----------------------------------------------------
 586
 587 To disable the synchronized scrolling of editor and preview, open
 588 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
 589 search for ``Restructuredtext › Preview: Scroll``. Then uncheck
 590 :guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
 591 :guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
 592
 593 -------------------------------------------------------------------------------
 594
 595 Miscellaneous
 596 =============
 597
 598 .. note:: This section is optional and should not be understood as a
 599    requirement.
 600
 601 Firefox Add-ons
 602 ---------------
 603
 604 Open :guilabel:`Add-Ons and Themes`, then search and install the following
 605 add-ons:
 606
 607 +------------------------------+-------------------------------+
 608 | I don't care about cookies   | Get rid of cookie warnings.   |
 609 +------------------------------+-------------------------------+
 610 | UBlock Origin                | A wide-spectrum blocker.      |
 611 +------------------------------+-------------------------------+
 612 | LastPass Password Manager    | Used in the Linux Foundation. |
 613 +------------------------------+-------------------------------+
 614
 615 ReText Editor
 616 -------------
 617
 618 Install this simple editor with ...
 619
 620 .. code-block:: bash
 621
 622    sudo apt install -y retext
 623
 624 -------------------------------------------------------------------------------
 625
 626 Helpful Resources
 627 =================
 628
 629 This is a collection of helpful resources if you want to extend and deepen your
 630 knowledge.
 631
 632 Documentation
 633 -------------
 634
 635 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
 636 - `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
 637
 638 Gerrit
 639 ------
 640
 641 - `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
 642
 643 Git
 644 ---
 645
 646 - `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
 647 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
 648
 649 ONAP Documentation Procedures for Developers
 650 --------------------------------------------
 651
 652 - `Procedure #1 for the ONAP Documentation Team <https://wiki.onap.org/x/-IpkBg>`__
 653 - `Procedure #2 for all other ONAP Project Teams <https://wiki.onap.org/x/w4IEBw>`__
 654
 655 Python
 656 ------
 657
 658 - `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__
 659 - `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>`__
 660 - `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__
 661 - `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
 662 - `Linux Foundation Docs Conf (obsolete) <https://pypi.org/project/lfdocs-conf/>`__
 663
 664 ReadTheDocs
 665 -----------
 666
 667 - `Documentation <https://docs.readthedocs.io/en/stable/>`__
 668 - `GitHub <https://github.com/readthedocs/readthedocs.org/>`__
 669
 670 ReadTheDocs Sphinx Theme
 671 ------------------------
 672
 673 - `ReadTheDocs Sphinx Theme (Recommended Reading!) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
 674 - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
 675
 676 reStructuredText
 677 ----------------
 678
 679 - `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__
 680 - `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
 681 - `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
 682
 683
 684 ..
 685   currently unavailable
 686   - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
 687
 688
 689 Sphinx
 690 ------
 691
 692 - `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
 693
 694 Ubuntu
 695 ------
 696
 697 - `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
 698
 699 Visual Studio Code (VSC)
 700 ------------------------
 701
 702 - `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__
 703 - `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
 704 - `VSC Icons <https://github.com/microsoft/vscode-icons>`__
 705 - `reStructuredText Extension <https://docs.restructuredtext.net/>`__
 706
 707 -------------------------------------------------------------------------------
 708
 709 Backlog
 710 =======
 711
 712 There are still some open topics or issues in this guide. They are subject
 713 for one of the upcoming releases.
 714
 715  - consider ``pandoc`` in this guide?
 716  - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build
 717    Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives?
 718  - VSC extension configuration: Difference between "Workspace" and "User"?
 719  - link to full ``ssh`` install/config?
 720  - link to full ``git`` install/config?
 721  - how to limit line width to improve readability? setting in conf.py?
 722  - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
 723    :kbd:`X` Is this a problem in the RTD theme?
 724  - use ``menuselection``
 725    :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
 726  - evaluate and add VSC extension to "draw" tables in an aided way
 727  - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
 728  - find the reason for VSC error message
 729    ``Substitution definition "ShowApp" empty or invalid.``
 730  - find the reason for VSC error message
 731    ``Unexpected indentation``
 732  - find a solution to wrap lines in VSC automatically (79 chars limit)
 733  - evaluate ``snooty`` and describe functionality (build in? not a extension?)
 734  - add a table explaining the role of installed packages/extensions in every
 735    section
 736  - update instructions to enable use of latest reStructuredText VSC extension
 737
 738 ..
 739    #########################################################################
 740    EMBEDDED PICTURES & ICONS BELOW
 741    #########################################################################
 742
 743 .. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
 744    :width: 20
 745
 746 .. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
 747    :width: 20
 748
 749 .. |FileExpl| image:: ./media/files.svg
 750    :width: 20
 751
 752 .. |GearSymb| image:: ./media/gear.svg
 753    :width: 20