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)
  43
  44 Last Review/Update
  45    2022/10/25
  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 If you plan to contribute to the ONAP community and you want to submit changes
  82 to a specific project later on, please refer to the
  83 `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
  84 and the `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information
  85 about all the prerequisite details.
  86
  87 -------------------------------------------------------------------------------
  88
  89 VM Configuration
  90 ================
  91
  92 .. note:: This section is for information only and should not be understood as
  93           a requirement.
  94
  95 Ubuntu Image Used
  96 -----------------
  97
  98 +--------------------------------------+
  99 | ubuntu-22.04.1-desktop-amd64.iso     |
 100 +--------------------------------------+
 101
 102 Please check what image must be used for your type of hardware.
 103
 104 VM Configuration
 105 ----------------
 106
 107 +-------------------------+------------+
 108 | Memory                  | 8 GB       |
 109 +-------------------------+------------+
 110 | Processors / Cores each | 2 / 2      |
 111 +-------------------------+------------+
 112 | Hard Disk               | 64 GB      |
 113 +-------------------------+------------+
 114
 115 Depending on your requirements you can modify the values for virtual memory,
 116 processors, cores or hard disk space.
 117
 118 VM Setup
 119 --------
 120
 121 Follow the instructions of your virtualization solution to install Ubuntu in a
 122 virtual machine. Log in after the installation has finished.
 123
 124 -------------------------------------------------------------------------------
 125
 126 Ubuntu Configuration
 127 ====================
 128
 129 .. note:: This section is optional and should not be understood as a
 130    requirement.
 131
 132 Finding Applications
 133 --------------------
 134
 135 The following actions are performed on the Ubuntu desktop. You may use the
 136 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
 137 the bottom left corner) to find the required applications. Later on you need to
 138 start also a :guilabel:`Terminal` window from here.
 139
 140 Software Updates
 141 ----------------
 142
 143 Open :guilabel:`Software Updater` and update installed Ubuntu packages.
 144 You may need to restart the system afterwards.
 145
 146 Maybe you need to force a snap-store update with the following commands:
 147
 148 .. code-block:: bash
 149
 150    snap-store --quit
 151    sudo snap refresh
 152
 153 Open :guilabel:`Ubuntu Software` again and check the :guilabel:`Updates` tab
 154 for required actions.
 155
 156 Screen Lock
 157 -----------
 158
 159 Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
 160 :guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
 161 and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
 162 window.
 163
 164 -------------------------------------------------------------------------------
 165
 166 An older version of Ubuntu LTS (e.g. 20.4.) may need additional configuration
 167 steps for proper localization:
 168
 169 Language Support
 170 ----------------
 171
 172 Open :guilabel:`Language Support`. You are asked to complete the installation.
 173 Select the :guilabel:`Install` button to complete. Continue in the
 174 :guilabel:`Language Support` window and open
 175 :guilabel:`Install / Remove Languages`. Then select your preferred
 176 :guilabel:`<LANGUAGE>`. Choose :guilabel:`Apply` to install the additional
 177 language.
 178
 179 Regional Formats
 180 ----------------
 181
 182 Continue to the :guilabel:`Regional Formats` tab. Select a
 183 :guilabel:`<FORMAT>` to show e.g. date, time and numbers in your preferred
 184 format. Press :guilabel:`Close` to close the window.
 185
 186 Input Sources
 187 -------------
 188
 189 To change the keyboard layout used e.g. in command line windows, open
 190 :guilabel:`Settings`. Navigate to :guilabel:`Region & Language`. At
 191 :guilabel:`Input Sources` press the :guilabel:`+` sign. Select your preferred
 192 :guilabel:`<INPUTSOURCE>` and use :guilabel:`Add` to add it. Move it to the top
 193 of the list using drag and drop. Close the window. You may need to logout from
 194 the UI and login again to make your changes effective.
 195
 196 -------------------------------------------------------------------------------
 197
 198 Disable sudo password for your user
 199 ===================================
 200
 201 .. warning:: This section is optional and should not be understood as a
 202    requirement. Disabling password authentication for all commands is very
 203    convenient at use **but it strongly exposes your system to malicious code**.
 204    For a system dedicated to development it might be OK, but not for a
 205    production system! Handle with care. You have been warned.
 206
 207 Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ...
 208
 209 .. code-block:: bash
 210
 211    sudo visudo
 212
 213 and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
 214 ``<USER>`` with your user name.
 215
 216 -------------------------------------------------------------------------------
 217
 218 Install python3 related packages
 219 ================================
 220
 221 .. important:: The main python3 package comes preinstalled with Ubuntu
 222
 223 Open a :guilabel:`Terminal` window and update the package management system
 224 with ...
 225
 226 .. code-block:: bash
 227
 228    cd ~
 229    sudo apt update
 230    sudo apt -y upgrade
 231
 232 Install python3 related packages with ...
 233
 234 .. code-block:: bash
 235
 236    sudo apt install -y python3-pip \
 237                        build-essential \
 238                        libssl-dev \
 239                        libffi-dev \
 240                        python3-dev \
 241                        python3-venv
 242
 243
 244 Check the python3 version with ...
 245
 246 .. code-block:: bash
 247
 248    python3 -V
 249
 250 -------------------------------------------------------------------------------
 251
 252 Install git and documentation related packages
 253 ==============================================
 254
 255 Install the required packages with ...
 256
 257 .. code-block:: bash
 258
 259    sudo apt install -y git \
 260                        git-review \
 261                        python-wheel-common \
 262                        python3-sphinx \
 263                        python3-doc8 \
 264                        graphviz \
 265                        docutils \
 266                        curl \
 267                        tox \
 268                        jq
 269
 270
 271 Check git version and the path of the sphinx-build executable with ...
 272
 273 .. code-block:: bash
 274
 275    git --version
 276
 277    which sphinx-build
 278
 279 -------------------------------------------------------------------------------
 280
 281 Install Visual Studio Code (VSC) and update applications
 282 ========================================================
 283
 284 The following actions are performed on the Ubuntu desktop. You may use the
 285 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
 286 the bottom left corner) to find the required applications.
 287
 288 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
 289 :guilabel:`vscode` (Visual Studio Code) and press :guilabel:`Install` to
 290 install the integrated development environment (IDE).
 291
 292 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
 293 installed applications are up to date.
 294
 295 -------------------------------------------------------------------------------
 296
 297 Configure ssh
 298 =============
 299
 300 If you already have a LF account and you have shared your public ssh key you
 301 can finalize the configuration of this development system by updating your ssh
 302 configuration in the ``~/.ssh`` directory by copying over ``config``,
 303 ``id_{algorithm}`` and ``id_{algorithm}.pub``
 304
 305 .. warning:: If your ssh key has been generated using the RSA SHA-1 hash
 306    algorithm, you may experience problems when connecting to other systems.
 307
 308    The RSA SHA-1 hash algorithm has been quickly deprecated across operating
 309    systems and SSH clients because of various security vulnerabilities,
 310    with many of these technologies now outright denying the use of this
 311    algorithm. You need to create new ssh keys using a more secure algorithm.
 312
 313    You may try to temporarily enable the insecure RSA SHA-1 hash algorithm by
 314    adding the line ``PubkeyAcceptedKeyTypes +ssh-rsa`` to your ssh ``config``
 315    file.
 316
 317 .. tip:: Please refer to the
 318    `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
 319    for additional information.
 320
 321 -------------------------------------------------------------------------------
 322
 323 Configure git
 324 =============
 325
 326 Configure ``git`` and ``git-review`` with ...
 327
 328 .. code-block:: bash
 329
 330    git config --global user.email "<GIT-EMAIL>"
 331    git config --global user.name "<GIT-USER>"
 332    git config --global --add gitreview.username "<GIT-USER>"
 333    git config --global gitreview.remote origin
 334
 335 Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
 336
 337 .. tip:: Please refer to the
 338    `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
 339    for additional information.
 340
 341 -------------------------------------------------------------------------------
 342
 343 Create working directory
 344 ========================
 345
 346 Create the working directory ``onapdocs`` in your home directory together with
 347 a ``repos`` directory to store various projects and versions. The full path is
 348 consequently ``~/onapdocs/repos``.
 349
 350 .. code-block:: bash
 351
 352    cd ~
 353    mkdir onapdocs
 354    cd onapdocs
 355    mkdir repos
 356    cd repos
 357
 358 -------------------------------------------------------------------------------
 359
 360 Clone example repo (no LF account)
 361 ==================================
 362
 363 Clone repo
 364 ----------
 365
 366 For a quick start you can clone e.g. the ``doc`` repository even without a
 367 Linux Foundation (LF) account with ...
 368
 369 .. code-block:: bash
 370
 371    cd ~/onapdocs/repos
 372    git clone --branch master https://git.onap.org/doc/ ./doc
 373
 374 -------------------------------------------------------------------------------
 375
 376 Clone example repo (LF account used)
 377 ====================================
 378
 379 Clone repo
 380 ----------
 381
 382 .. code-block:: bash
 383
 384    cd ~/onapdocs/repos
 385    git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
 386
 387 -------------------------------------------------------------------------------
 388
 389 Install required Sphinx packages
 390 ================================
 391
 392 .. important:: By using ``sudo pip ...`` you will see a message saying:
 393    "*WARNING: Running pip as the 'root' user can result in broken permissions
 394    and conflicting behaviour with the system package manager*". We try to avoid
 395    this installation method in a later version of this guide.
 396
 397 Install required Sphinx packages using the file ``requirements-docs.txt`` as an
 398 input. The file resides in the downloaded ``doc`` repository.
 399
 400 .. code-block:: bash
 401
 402    sudo pip install -r doc/etc/requirements-docs.txt
 403
 404 -------------------------------------------------------------------------------
 405
 406 Start VSC in the correct directory
 407 ==================================
 408
 409 Start VSC (always) in the ``docs`` directory of your repository. For the cloned
 410 ``doc`` repository used in this example do this with ...
 411
 412 .. code-block:: bash
 413
 414    cd doc/docs
 415    code .
 416
 417 .. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
 418
 419 .. tip:: ``~/onapdocs/repos/doc/docs`` is now your
 420    ``${workspaceFolder}`` because you have started VSC (``code .``) from here!
 421
 422 -------------------------------------------------------------------------------
 423
 424 Disable Telemetry of VSC
 425 ========================
 426
 427 In case you want to disable telemetry functionality of Visual Studio Code, open
 428 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Telemetry Settings` and
 429 turn it ``off`` in the selection field.
 430
 431 In an older version of VSC you alternatively need to open
 432 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
 433 search for ``telemetry``. Then uncheck
 434 :guilabel:`Telemetry: Enable Crash Reporter` and
 435 :guilabel:`Telemetry: Enable Telemetry`
 436
 437 .. warning:: Extensions may be collecting their own usage data and are not
 438    controlled by the ``telemetry.enableTelemetry`` setting. Consult the
 439    specific extension's documentation to learn about its telemetry
 440    reporting and whether it can be disabled. See also
 441    https://code.visualstudio.com/docs/getstarted/telemetry
 442
 443 -------------------------------------------------------------------------------
 444
 445 Install VSC extensions and configure them
 446 =========================================
 447
 448 Install VSC extensions
 449 ----------------------
 450
 451 Extension bring additional power to Visual Studio Code. To search and install
 452 them, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Extensions`
 453 or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the
 454 extension in the :guilabel:`Search Extensions in Marketplace` window.
 455 Press :guilabel:`Install` if you have found the required extension.
 456
 457 .. important:: You will experience, that VSC asks you to install additional
 458    components (e.g. Esbonio Language Server, reStructuredText Syntax
 459    Highlighting). It is important to allow VSC the installation!
 460
 461
 462 Please manually install ...
 463
 464 +---------------------------------------+--------------------+------------+
 465 | IDENTIFIER (search)                   | NAME               | TESTED     |
 466 +=======================================+====================+============+
 467 | ms-python.python                      | Python             | v2022.16.1 |
 468 +---------------------------------------+--------------------+------------+
 469 | lextudio.restructuredtext             | reStructuredText   | v189.1.0   |
 470 +---------------------------------------+--------------------+------------+
 471 | eamodio.gitlens                       | GitLens            | v13.0.3    |
 472 +---------------------------------------+--------------------+------------+
 473 | streetsidesoftware.code-spell-checker | Code Spell Checker | v2.10.1    |
 474 +---------------------------------------+--------------------+------------+
 475 | esbenp.prettier-vscode                | Prettier           | v9.9.0     |
 476 +---------------------------------------+--------------------+------------+
 477
 478 Together with the above extensions, the following software is automatically
 479 installed ...
 480
 481 +----------------------------+--------------------------------------+-------------+
 482 | IDENTIFIER (search)        | NAME                                 | TESTED      |
 483 +============================+======================================+=============+
 484 | ms-python.vscode-pylance   | Pylance                              | v2022.10.30 |
 485 +----------------------------+--------------------------------------+-------------+
 486 | several Jupyter Extensions | Jupyter ...                          | ...         |
 487 +----------------------------+--------------------------------------+-------------+
 488 | snekvik.simple-rst         | reStructuredText Syntax highlighting | v1.5.2      |
 489 +----------------------------+--------------------------------------+-------------+
 490
 491
 492 Close VSC and restart it using the ``code .`` command.
 493
 494 Configure reStructuredText extension
 495 ------------------------------------
 496
 497 To configure ``reStructuredText`` extension, open :guilabel:`File` >
 498 :guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut
 499 ``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the
 500 :guilabel:`Search Extensions in Marketplace` window. After you have found the
 501 extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
 502 bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
 503 all the parameters.
 504
 505 Values for the following parameters need to be changed:
 506
 507 - Restructuredtext › Linter › Doc8: Executable Path
 508 - Restructuredtext › Linter › Rst-lint: Executable Path
 509 - Restructuredtext › Linter › Rstcheck: Executable Path
 510 - Esbonio › Sphinx: Build Dir
 511 - Restructuredtext: Styles
 512
 513
 514 .. important:: Ensure that you are changing parameters in :guilabel:`User`
 515    Settings and :strong:`not` in :guilabel:`Workspace` Settings.
 516    :guilabel:`User` Settings are applied globally - for every running instance
 517    of VSC.
 518
 519 .. tip:: If you experience problems adding the value to
 520    ``restructuredtext.styles`` via editing the ``settings.json`` in VSC, please
 521    use an external editor (e.g. ``vi``) to add the value.
 522
 523 Search the following parameter in the :guilabel:`Search settings` field and add
 524 the listed values:
 525
 526 .. list-table:: VSC User Settings for reStructuredText
 527     :header-rows: 1
 528
 529     * - PARAMETER (search)
 530       - VALUE
 531     * - restructuredtext.linter.doc8.executablePath
 532       - /usr/bin/doc8
 533     * - restructuredtext.linter.rst-lint.executablePath
 534       - /usr/bin/doc8
 535     * - restructuredtext.linter.rstcheck.executablePath
 536       - /usr/bin/doc8
 537     * - esbonio.sphinx.buildDir
 538       - ${workspaceFolder}/_build
 539     * - restructuredtext.styles
 540       - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css
 541
 542 Close the :guilabel:`Extension Settings` window.
 543
 544 Close VSC and restart it using the ``code .`` command.
 545
 546 Your VSC User Settings file ``/home/<USER>/.config/Code/User/settings.json``
 547 should now include the following entries:
 548
 549 .. code-block:: bash
 550
 551    {
 552        "telemetry.telemetryLevel": "off",
 553        "restructuredtext.linter.doc8.executablePath": "/usr/bin/doc8",
 554        "restructuredtext.linter.rst-lint.executablePath": "/usr/bin/doc8",
 555        "restructuredtext.linter.rstcheck.executablePath": "/usr/bin/doc8",
 556        "esbonio.sphinx.buildDir": "${workspaceFolder}/_build",
 557        "restructuredtext.styles": [
 558          "/usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css"
 559        ]
 560    }
 561
 562 -------------------------------------------------------------------------------
 563
 564 Open a .rst file and preview it in VSC
 565 ======================================
 566
 567 Open .rst file
 568 --------------
 569
 570 Select :guilabel:`View` > :guilabel:`Explorer`. Or use the |FileExpl| symbol in
 571 the upper left corner. Expand the ``docs`` folder by clicking on the ``>``
 572 symbol. Select the file ``index.rst``. The code shows up in the right pane
 573 window of VSC.
 574
 575 Alternatively you can open this guide and see how it looks like in the
 576 reStructuredText format. It can be found in ``docs/guides/onap-documentation``
 577 and is named ``setup-of-a-doc-dev-system.rst``.
 578
 579 Problem Window
 580 --------------
 581
 582 You may see problems with the reStructuredText markup because the code is
 583 underlined in various colors. For the details select :guilabel:`View` >
 584 :guilabel:`Problems` to open an additional window at the bottom of VSC.
 585
 586 When you select a specific entry in the problem list, the code window is
 587 updated to show the related line in the code. To show only problems for the
 588 :strong:`active` file in VSC, set the filter to
 589 :guilabel:`Show Active File Only`.
 590
 591 Preview
 592 -------
 593
 594 Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top
 595 right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window
 596 on the right hand side. This may take a few seconds. The preview shows up and
 597 renders the ``index.rst`` as it would look like on ReadTheDocs.
 598
 599 Build documentation locally
 600 ---------------------------
 601
 602 To build documentation locally use the ``tox`` command, check the output for
 603 error messages and check the files using your favorite browser.
 604
 605 .. code-block:: bash
 606
 607     cd ~/onapdocs/repos/doc
 608     tox
 609     ... (checks are executed, docs are build, check logging output) ...
 610     cd docs/_build/html
 611     firefox ./index.html
 612
 613
 614 Tips and Tricks
 615 ---------------
 616
 617 The learnings are ...
 618
 619 .. tip::
 620    - Start VSC always in the ``docs`` directory of the repository. Use the
 621      command ``code .``. Then navigate via VSC's :guilabel:`Explorer`
 622      |FileExpl| to the directory which contains the file you like to edit. VSC
 623      may ask you, which ``conf.py`` VSC should use. Choose the one which
 624      resides in the directory where you have started VSC. Check also the (blue)
 625      bottom line of VSC. There you see which ``conf.py`` is currently in use.
 626      The content of ``conf.py`` affects how the documentation is presented.
 627    - VSC may claim that some packages require an update. This can be easily
 628      fixed. VSC offers automatically to install or update the package.
 629    - Select the correct environment in the (blue) bottom line
 630      ``'onapdocs':venv``. Have also a view on the other interesting
 631      information (e.g. the ``conf.py`` which is currently in use).
 632    - First, close and reopen preview if preview is not shown properly.
 633    - Second, close and reopen VSC if preview is not shown properly.
 634    - Save your file if an error does not disappear after you have corrected it.
 635    - You can not navigate within the document structure by clicking the links
 636      in the preview. You always have to choose the correct file in the VSC
 637      :guilabel:`Explorer` window.
 638
 639 That's it!
 640 ----------
 641
 642 Congratulations, well done! You have configured a system well suited to
 643 develop ONAP documentation and to master the challenges of reStructuredText.
 644 Now have a look at all the different elements of reStructuredText and learn how
 645 to use them properly. Or maybe you like to do some optional configurations at
 646 your system first.
 647
 648 -------------------------------------------------------------------------------
 649
 650 Optional VSC Configuration
 651 ==========================
 652
 653 Add Ruler
 654 ---------
 655
 656 To add a ruler that indicates the line end at 79 characters, open
 657 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
 658 ``ruler`` in the :guilabel:`Search settings` field. In
 659 :guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add
 660 the value ``79``. The result should look like this:
 661
 662 .. code-block:: bash
 663
 664     "editor.rulers": [
 665         79
 666     ]
 667
 668 Disable Synchronized Scrolling of Editor and Preview
 669 ----------------------------------------------------
 670
 671 To disable the synchronized scrolling of editor and preview, open
 672 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
 673 search for ``Restructuredtext › Preview: Scroll``. Then uncheck
 674 :guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
 675 :guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
 676
 677 -------------------------------------------------------------------------------
 678
 679 Miscellaneous
 680 =============
 681
 682 .. note:: This section is optional and should not be understood as a
 683    requirement.
 684
 685 Firefox Add-ons
 686 ---------------
 687
 688 Open :guilabel:`Add-Ons and Themes`, then search and install the following
 689 add-ons:
 690
 691 +------------------------------+-------------------------------+
 692 | I don't care about cookies   | Get rid of cookie warnings.   |
 693 +------------------------------+-------------------------------+
 694 | UBlock Origin                | A wide-spectrum blocker.      |
 695 +------------------------------+-------------------------------+
 696 | LastPass Password Manager    | Used in the Linux Foundation. |
 697 +------------------------------+-------------------------------+
 698
 699 ReText Editor
 700 -------------
 701
 702 Install this simple editor with ...
 703
 704 .. code-block:: bash
 705
 706    sudo apt install -y retext
 707
 708 Ubuntu Restricted Extras
 709 ------------------------
 710
 711 If you experience problems during playback of some audio or video formats on
 712 your system, please check the ``ubuntu-restricted-extras`` package.
 713
 714 -------------------------------------------------------------------------------
 715
 716 Helpful Resources
 717 =================
 718
 719 This is a collection of helpful resources if you want to extend and deepen your
 720 knowledge.
 721
 722 Documentation
 723 -------------
 724
 725 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
 726 - `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
 727
 728 Gerrit
 729 ------
 730
 731 - `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
 732
 733 Git/GitHub
 734 ----------
 735
 736 - `GitHub Authentication <https://docs.github.com/en/authentication>`__
 737 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
 738 - `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
 739
 740 Linux Foundation Release Engineering
 741 ------------------------------------
 742
 743 - `LF RelEng Documentation (recommended reading) <https://docs.releng.linuxfoundation.org>`__
 744
 745
 746 ONAP Documentation Procedures for Developers
 747 --------------------------------------------
 748
 749 - `Procedure #1 for the ONAP Documentation Team <https://wiki.onap.org/x/-IpkBg>`__
 750 - `Procedure #2 for all other ONAP Project Teams <https://wiki.onap.org/x/w4IEBw>`__
 751
 752 Python
 753 ------
 754
 755 - `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__
 756 - `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>`__
 757 - `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__
 758 - `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
 759 - `Linux Foundation Docs Conf (obsolete) <https://pypi.org/project/lfdocs-conf/>`__
 760
 761 ReadTheDocs
 762 -----------
 763
 764 - `Documentation <https://docs.readthedocs.io/en/stable/>`__
 765 - `Tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`__
 766 - `GitHub <https://github.com/readthedocs/readthedocs.org/>`__
 767
 768 ReadTheDocs Sphinx Theme
 769 ------------------------
 770
 771 - `ReadTheDocs Sphinx Theme (recommended reading) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
 772 - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
 773
 774 reStructuredText
 775 ----------------
 776
 777 - `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__
 778 - `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
 779 - `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
 780
 781
 782 ..
 783   currently unavailable
 784   - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
 785
 786
 787 Sphinx
 788 ------
 789
 790 - `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
 791
 792
 793 Visual Studio Code (VSC)
 794 ------------------------
 795
 796 - `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__
 797 - `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
 798 - `VSC Icons <https://github.com/microsoft/vscode-icons>`__
 799 - `reStructuredText Extension <https://docs.restructuredtext.net/>`__
 800
 801 -------------------------------------------------------------------------------
 802
 803 Backlog
 804 =======
 805
 806 There are still some open topics or issues in this guide. They are subject
 807 for one of the upcoming releases.
 808
 809 - fix issues with virtual environments using different python versions in VCS
 810 - consider ``pandoc`` in this guide?
 811 - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
 812   :kbd:`X` Is this a problem in the RTD theme?
 813 - use ``menuselection``
 814   :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
 815 - evaluate and add VSC extension to "draw" tables in an aided way
 816 - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
 817 - find the reason for VSC error message
 818   ``Substitution definition "ShowApp" empty or invalid.``
 819 - find the reason for VSC error message
 820   ``Unexpected indentation``
 821 - find a solution to wrap lines in VSC automatically (79 chars limit)
 822 - add a table explaining the role of installed packages/extensions in every
 823   section
 824
 825 ..
 826    #########################################################################
 827    EMBEDDED PICTURES & ICONS BELOW
 828    #########################################################################
 829
 830 .. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
 831    :width: 20
 832
 833 .. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
 834    :width: 20
 835
 836 .. |FileExpl| image:: ./media/files.svg
 837    :width: 20
 838
 839 .. |GearSymb| image:: ./media/gear.svg
 840    :width: 20