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
7 *******************************************
8 Setup of a Documentation Development System
9 *******************************************
13 #########################################################################
14 HOW TO FILL THIS SECTION:
17 Name the ONAP release(s) where this document has a relevance.
18 ONAP release number (ONAP release name starting with a capital letter)
20 8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
21 7.0.1 (Guilin) - 3.0.0 (Casablanca), 1.0.0 (Amsterdam)
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).
29 Initial release date of this document.
30 Use en-US format (mm/dd/yyyy).
33 Name of the author and company name. Use comma to separate.
35 Jane Doe (ACME), John Doe (ACME)
37 ! PLEASE DO NOT CHANGE THE STRUCTURE OF THIS SECTION.
38 ! PLEASE ADD ONLY REQUESTED INFORMATION BELOW!
39 #########################################################################
42 11.x.x (Kohn) - 10.x.x (Jakarta)
51 Thomas Kulik (Deutsche Telekom AG)
53 -------------------------------------------------------------------------------
55 .. contents:: Table of Contents
57 -------------------------------------------------------------------------------
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.
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.
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>`__.
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.
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.
87 -------------------------------------------------------------------------------
92 .. note:: This section is for information only and should not be understood as
98 +--------------------------------------+
99 | ubuntu-22.04.1-desktop-amd64.iso |
100 +--------------------------------------+
102 Please check what image must be used for your type of hardware.
107 +-------------------------+------------+
109 +-------------------------+------------+
110 | Processors / Cores each | 2 / 2 |
111 +-------------------------+------------+
112 | Hard Disk | 64 GB |
113 +-------------------------+------------+
115 Depending on your requirements you can modify the values for virtual memory,
116 processors, cores or hard disk space.
121 Follow the instructions of your virtualization solution to install Ubuntu in a
122 virtual machine. Log in after the installation has finished.
124 -------------------------------------------------------------------------------
129 .. note:: This section is optional and should not be understood as a
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.
143 Open :guilabel:`Software Updater` and update installed Ubuntu packages.
144 You may need to restart the system afterwards.
149 Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
150 :guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
151 and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
154 -------------------------------------------------------------------------------
156 An older version of Ubuntu LTS (e.g. 20.4.) may need additional configuration
157 steps for proper localization:
162 Open :guilabel:`Language Support`. You are asked to complete the installation.
163 Select the :guilabel:`Install` button to complete. Continue in the
164 :guilabel:`Language Support` window and open
165 :guilabel:`Install / Remove Languages`. Then select your preferred
166 :guilabel:`<LANGUAGE>`. Choose :guilabel:`Apply` to install the additional
172 Continue to the :guilabel:`Regional Formats` tab. Select a
173 :guilabel:`<FORMAT>` to show e.g. date, time and numbers in your preferred
174 format. Press :guilabel:`Close` to close the window.
179 To change the keyboard layout used e.g. in command line windows, open
180 :guilabel:`Settings`. Navigate to :guilabel:`Region & Language`. At
181 :guilabel:`Input Sources` press the :guilabel:`+` sign. Select your preferred
182 :guilabel:`<INPUTSOURCE>` and use :guilabel:`Add` to add it. Move it to the top
183 of the list using drag and drop. Close the window. You may need to logout from
184 the UI and login again to make your changes effective.
186 -------------------------------------------------------------------------------
188 Disable sudo password for your user
189 ===================================
191 .. warning:: This section is optional and should not be understood as a
192 requirement. Disabling password authentication for all commands is very
193 convenient at use **but it strongly exposes your system to malicious code**.
194 For a system dedicated to development it might be OK, but not for a
195 production system! Handle with care. You have been warned.
197 Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ...
203 and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
204 ``<USER>`` with your user name.
206 -------------------------------------------------------------------------------
208 Install python3 related packages
209 ================================
211 .. important:: The main python3 package is preinstalled in Ubuntu. But please
212 ensure that you are using python version 3.8 or higher.
214 Open a :guilabel:`Terminal` window and update the package management system
223 Install python3 related packages with ...
227 sudo apt install -y python3-pip \
235 Check the python3 version with ...
241 -------------------------------------------------------------------------------
243 Install git and documentation related packages
244 ==============================================
246 Install the required packages with ...
250 sudo apt install -y git \
259 Check git version and the path of the sphinx-build executable with ...
267 -------------------------------------------------------------------------------
269 Install Visual Studio Code (VSC) and update applications
270 ========================================================
272 The following actions are performed on the Ubuntu desktop. You may use the
273 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
274 the bottom left corner) to find the required applications.
276 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
277 :guilabel:`vscode` (Visual Studio Code) and press :guilabel:`Install` to
278 install the integrated development environment (IDE).
280 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
281 installed applications are up to date.
283 -------------------------------------------------------------------------------
288 If you already have a LF account and you have shared your public ssh key you
289 can finalize the configuration of this development system by updating your ssh
290 configuration in the ``~/.ssh`` directory by copying over ``config``,
291 ``id_{algorithm}`` and ``id_{algorithm}.pub``
293 .. warning:: If your ssh key has been generated using the RSA SHA-1 hash
294 algorithm, you may experience problems when connecting to other systems.
296 The RSA SHA-1 hash algorithm has been quickly deprecated across operating
297 systems and SSH clients because of various security vulnerabilities,
298 with many of these technologies now outright denying the use of this
299 algorithm. You need to create new ssh keys using a more secure algorithm.
301 You may try to temporarily enable the insecure RSA SHA-1 hash algorithm by
302 adding the line ``PubkeyAcceptedKeyTypes +ssh-rsa`` to your ssh ``config``
305 .. tip:: Please refer to the
306 `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
307 for additional information.
309 -------------------------------------------------------------------------------
314 Configure ``git`` and ``git-review`` with ...
318 git config --global user.email "<GIT-EMAIL>"
319 git config --global user.name "<GIT-USER>"
320 git config --global --add gitreview.username "<GIT-USER>"
321 git config --global gitreview.remote origin
323 Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
325 .. tip:: Please refer to the
326 `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
327 for additional information.
329 -------------------------------------------------------------------------------
331 Create virtual environment and activate
332 =======================================
334 In this guide, virtual environments are generally located in your home
335 directory under ``~/environments``. For the development of ONAP documentation
336 the virtual environment ``onapdocs`` is created. The full path is consequently
337 ``~/environments/onapdocs``.
344 python3 -m venv onapdocs
345 cd ~/environments/onapdocs
348 To indicate that you are now working in an virtual environment, the prompt of
349 your terminal has changed. Now it starts with ``(onapdocs)``.
351 -------------------------------------------------------------------------------
353 Clone example repo (no LF account)
354 ==================================
359 For a quick start you can clone e.g. the ``doc`` repository even without a
360 Linux Foundation (LF) account with ...
364 cd ~/environments/onapdocs
365 git clone --branch master https://git.onap.org/doc/ ./doc
367 -------------------------------------------------------------------------------
369 Clone example repo (LF account used)
370 ====================================
377 cd ~/environments/onapdocs
378 git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
380 -------------------------------------------------------------------------------
382 Install required Sphinx packages in activated environment
383 =========================================================
385 It is :strong:`important` to work in the ``onapdocs`` virtual environment. If
386 not already done, activate environment with ...
390 cd ~/environments/onapdocs
393 To indicate that you are now working in an virtual environment, the prompt of
394 your terminal has changed. Now it starts with ``(onapdocs)``.
396 .. important:: Now you are installing packages only for the 'onapdocs' virtual
403 Continue with the installation of required packages. Use the file
404 ``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
409 cd ~/environments/onapdocs
410 sudo pip install -r doc/etc/requirements-docs.txt
412 -------------------------------------------------------------------------------
414 Start VSC in the correct directory
415 ==================================
417 Start VSC (always) in the ``docs`` directory of your repository. For the
418 ``doc`` repository used in this example do this with ...
425 .. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
427 .. tip:: ``~/environments/onapdocs/doc/docs`` is now your
428 ``${workspaceFolder}`` because you have started VSC (``code .``) from here!
430 -------------------------------------------------------------------------------
432 Disable Telemetry of VSC
433 ========================
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.
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`
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
451 -------------------------------------------------------------------------------
453 Install VSC extensions and configure them
454 =========================================
456 Install VSC extensions
457 ----------------------
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.
467 +---------------------------------------+--------------------------------------+-------------+
468 | IDENTIFIER (search) | NAME | TESTED |
469 +=======================================+======================================+=============+
470 | ms-python.python | Python | v2022.14.0 |
471 +---------------------------------------+--------------------------------------+-------------+
472 | lextudio.restructuredtext | reStructuredText | v189.1.0 |
473 +---------------------------------------+--------------------------------------+-------------+
474 | trond-snekvik.simple-rst | reStructuredText Syntax highlighting | v1.5.2 |
475 +---------------------------------------+--------------------------------------+-------------+
476 | eamodio.gitlens | GitLens | v12.2.1 |
477 +---------------------------------------+--------------------------------------+-------------+
478 | streetsidesoftware.code-spell-checker | Code Spell Checker | v2.7.2 |
479 +---------------------------------------+--------------------------------------+-------------+
481 Close VSC and restart it using the ``code .`` command.
483 You may experience, that VSC asks you to install additional components
484 (e.g. the Esbonio Language Server). Please allow VSC to install them.
486 Configure reStructuredText extension
487 ------------------------------------
489 To configure ``reStructuredText`` extension, open :guilabel:`File` >
490 :guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut
491 ``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the
492 :guilabel:`Search Extensions in Marketplace` window. After you have found the
493 extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
494 bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
497 We need to change values for ...
499 ``Restructuredtext › Linter › Doc8: Executable Path``
501 ``Restructuredtext › Linter › Rst-lint: Executable Path``
503 ``Restructuredtext › Linter › Rstcheck: Executable Path``
505 ``Esbonio › Sphinx: Build Dir``
507 ``Esbonio › Sphinx: Conf Dir``
509 ``Esbonio › Sphinx: Src Dir``
511 ``Restructuredtext: Styles``
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
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.
523 Search the following parameter in the :guilabel:`Search settings` field and add
526 .. list-table:: VSC User Settings for reStructuredText
529 * - PARAMETER (search)
531 * - restructuredtext.linter.doc8.executablePath
533 * - restructuredtext.linter.rst-lint.executablePath
535 * - restructuredtext.linter.rstcheck.executablePath
537 * - restructuredtext.styles
538 - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css
539 * - esbonio.sphinx.buildDir
540 - ${workspaceFolder}/_build/html
541 * - esbonio.sphinx.confDir
543 * - esbonio.sphinx.srcDir
547 Close the :guilabel:`Extension Settings` window.
549 Close VSC and restart it using the ``code .`` command.
551 Your VSC User Settings file ``/home/<USER>/.config/Code/User/settings.json``
552 should now include the following entries:
556 "telemetry.telemetryLevel": "off",
557 "restructuredtext.linter.doc8.executablePath": "/usr/bin/doc8",
558 "restructuredtext.linter.rst-lint.executablePath": "/usr/bin/doc8",
559 "restructuredtext.linter.rstcheck.executablePath": "/usr/bin/doc8",
560 "restructuredtext.styles": [
561 /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css
563 "esbonio.sphinx.buildDir": "${workspaceFolder}/_build/html",
564 "esbonio.sphinx.confDir": "${workspaceFolder}",
565 "esbonio.sphinx.srcDir": "${workspaceFolder}"
568 -------------------------------------------------------------------------------
570 Open a .rst file and preview it in VSC
571 ======================================
576 Select :guilabel:`View` > :guilabel:`Explorer`. Or use the |FileExpl| symbol in
577 the upper left corner. Expand the ``docs`` folder by clicking on the ``>``
578 symbol. Select the file ``index.rst``. The code shows up in the right pane
581 Alternatively you can open this guide and see how it looks like in the
582 reStructuredText format. It can be found in ``docs/guides/onap-documentation``
583 and is named ``setup-of-a-doc-dev-system.rst``.
588 You may see problems with the reStructuredText markup because the code is
589 underlined in various colors. For the details select :guilabel:`View` >
590 :guilabel:`Problems` to open an additional window at the bottom of VSC.
592 When you select a specific entry in the problem list, the code window is
593 updated to show the related line in the code. To show only problems for the
594 :strong:`active` file in VSC, set the filter to
595 :guilabel:`Show Active File Only`.
600 Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top
601 right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window
602 on the right hand side. This may take a few seconds. The preview shows up and
603 renders the ``index.rst`` as it would look like on ReadTheDocs.
608 The learnings are ...
611 - Start VSC always in the ``docs`` directory of the repository. Use the
612 command ``code .``. Then navigate via VSC's :guilabel:`Explorer`
613 |FileExpl| to the directory which contains the file you like to edit. VSC
614 may ask you, which ``conf.py`` VSC should use. Choose the one which
615 resides in the directory where you have started VSC. Check also the (blue)
616 bottom line of VSC. There you see which ``conf.py`` is currently in use.
617 The content of ``conf.py`` affects how the documentation is presented.
618 - VSC may claim that some packages require an update. This can be easily
619 fixed. VSC offers automatically to install or update the package.
620 - Select the correct environment in the (blue) bottom line
621 ``'onapdocs':venv``. Have also a view on the other interesting
622 information (e.g. the ``conf.py`` which is currently in use).
623 - First, close and reopen preview if preview is not shown properly.
624 - Second, close and reopen VSC if preview is not shown properly.
625 - Save your file if an error does not disappear after you have corrected it.
626 - You can not navigate within the document structure by clicking the links
627 in the preview. You always have to choose the correct file in the VSC
628 :guilabel:`Explorer` window.
633 Congratulations, well done! You have configured a system well suited to
634 develop ONAP documentation and to master the challenges of reStructuredText.
635 Now have a look at all the different elements of reStructuredText and learn how
636 to use them properly. Or maybe you like to do some optional configurations at
639 -------------------------------------------------------------------------------
641 Optional VSC Configuration
642 ==========================
647 To add a ruler that indicates the line end at 79 characters, open
648 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
649 ``ruler`` in the :guilabel:`Search settings` field. In
650 :guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add
651 the value ``79``. The result should look like this:
659 Disable Synchronized Scrolling of Editor and Preview
660 ----------------------------------------------------
662 To disable the synchronized scrolling of editor and preview, open
663 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
664 search for ``Restructuredtext › Preview: Scroll``. Then uncheck
665 :guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
666 :guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
668 -------------------------------------------------------------------------------
673 .. note:: This section is optional and should not be understood as a
679 Open :guilabel:`Add-Ons and Themes`, then search and install the following
682 +------------------------------+-------------------------------+
683 | I don't care about cookies | Get rid of cookie warnings. |
684 +------------------------------+-------------------------------+
685 | UBlock Origin | A wide-spectrum blocker. |
686 +------------------------------+-------------------------------+
687 | LastPass Password Manager | Used in the Linux Foundation. |
688 +------------------------------+-------------------------------+
693 Install this simple editor with ...
697 sudo apt install -y retext
699 -------------------------------------------------------------------------------
704 This is a collection of helpful resources if you want to extend and deepen your
710 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
711 - `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
716 - `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
721 - `GitHub Authentication <https://docs.github.com/en/authentication>`__
722 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
723 - `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
725 Linux Foundation Release Engineering
726 ------------------------------------
728 - `LF RelEng Documentation (recommended reading) <https://docs.releng.linuxfoundation.org>`__
731 ONAP Documentation Procedures for Developers
732 --------------------------------------------
734 - `Procedure #1 for the ONAP Documentation Team <https://wiki.onap.org/x/-IpkBg>`__
735 - `Procedure #2 for all other ONAP Project Teams <https://wiki.onap.org/x/w4IEBw>`__
740 - `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__
741 - `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>`__
742 - `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__
743 - `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
744 - `Linux Foundation Docs Conf (obsolete) <https://pypi.org/project/lfdocs-conf/>`__
749 - `Documentation <https://docs.readthedocs.io/en/stable/>`__
750 - `Tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`__
751 - `GitHub <https://github.com/readthedocs/readthedocs.org/>`__
753 ReadTheDocs Sphinx Theme
754 ------------------------
756 - `ReadTheDocs Sphinx Theme (recommended reading) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
757 - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
762 - `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__
763 - `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
764 - `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
768 currently unavailable
769 - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
775 - `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
780 - `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
782 Visual Studio Code (VSC)
783 ------------------------
785 - `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__
786 - `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
787 - `VSC Icons <https://github.com/microsoft/vscode-icons>`__
788 - `reStructuredText Extension <https://docs.restructuredtext.net/>`__
790 -------------------------------------------------------------------------------
795 There are still some open topics or issues in this guide. They are subject
796 for one of the upcoming releases.
798 - consider ``pandoc`` in this guide?
799 - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
800 :kbd:`X` Is this a problem in the RTD theme?
801 - use ``menuselection``
802 :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
803 - evaluate and add VSC extension to "draw" tables in an aided way
804 - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
805 - find the reason for VSC error message
806 ``Substitution definition "ShowApp" empty or invalid.``
807 - find the reason for VSC error message
808 ``Unexpected indentation``
809 - find a solution to wrap lines in VSC automatically (79 chars limit)
810 - add a table explaining the role of installed packages/extensions in every
814 #########################################################################
815 EMBEDDED PICTURES & ICONS BELOW
816 #########################################################################
818 .. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
821 .. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
824 .. |FileExpl| image:: ./media/files.svg
827 .. |GearSymb| image:: ./media/gear.svg