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