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-20.04.3-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 already installed Ubuntu packages.
144 You may need to restart the system afterwards.
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
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.
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.
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
181 -------------------------------------------------------------------------------
183 Disable sudo password for your user
184 ===================================
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.
192 Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ...
198 and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
199 ``<USER>`` with your user name.
201 -------------------------------------------------------------------------------
203 Install python3 related packages
204 ================================
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.
209 Open a :guilabel:`Terminal` window and update the package management system
218 Install python3 related packages with ...
222 sudo apt install -y python3-pip \
230 Check the python3 version with ...
236 -------------------------------------------------------------------------------
238 Install git and documentation related packages
239 ==============================================
241 Install the required packages with ...
245 sudo apt install -y git \
253 Check git version and the path of the sphinx-build executable with ...
262 .. tip:: Remember the path
263 ``/usr/bin/sphinx-build``, you need it later
264 to configure a VSC extension.
266 -------------------------------------------------------------------------------
268 Install Visual Studio Code (VSC) and update applications
269 ========================================================
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.
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).
279 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
280 installed applications are up to date.
282 -------------------------------------------------------------------------------
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``
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.
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.
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``
304 .. tip:: Please refer to the
305 `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
306 for additional information.
308 -------------------------------------------------------------------------------
313 Configure ``git`` and ``git-review`` with ...
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
322 Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
324 .. tip:: Please refer to the
325 `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
326 for additional information.
328 -------------------------------------------------------------------------------
330 Create virtual environment and activate
331 =======================================
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``.
343 python3 -m venv onapdocs
344 cd ~/environments/onapdocs
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)``.
350 -------------------------------------------------------------------------------
352 Clone example repo (no LF account)
353 ==================================
358 For a quick start you can clone e.g. the ``doc`` repository even without a
359 Linux Foundation (LF) account with ...
363 cd ~/environments/onapdocs
364 git clone --branch master https://git.onap.org/doc/ ./doc
366 -------------------------------------------------------------------------------
368 Clone example repo (LF account used)
369 ====================================
376 cd ~/environments/onapdocs
377 git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
379 -------------------------------------------------------------------------------
381 Install required Sphinx packages in activated environment
382 =========================================================
384 It is :strong:`important` to work in the ``onapdocs`` virtual environment. If
385 not already done, activate environment with ...
389 cd ~/environments/onapdocs
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)``.
395 .. important:: Now you are installing packages only for the 'onapdocs' virtual
402 Continue with the installation of required packages. Use the file
403 ``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
408 cd ~/environments/onapdocs
409 sudo pip install -r doc/etc/requirements-docs.txt
411 -------------------------------------------------------------------------------
413 Start VSC in the correct directory
414 ==================================
416 Start VSC (always) in the ``docs`` directory of your repository. For the
417 ``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 reStructuredText extension
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 | 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 +--------------------------------------+---------------------------------------+---------+
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.
487 Configure reStructuredText extension
488 ------------------------------------
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:
498 :strong:`Restructuredtext › Linter: Executable Path`
501 :strong:`Restructuredtext › Linter: Name`
504 :strong:`Restructuredtext: Sphinx Build Path`
505 ``/usr/bin/sphinx-build``
507 Replace ``<USER>`` with your user name.
509 Only in case the preview creates an error message, try ...
511 :strong:`Restructuredtext: Conf Path`
512 ``${workspaceFolder}/docs``
514 Close the :guilabel:`Extension Settings` window.
516 Close VSC and start it again with the ``code .`` command.
518 -------------------------------------------------------------------------------
520 Open a .rst file and preview it in VSC
521 ======================================
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
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``.
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.
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.
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.
556 The learnings are ...
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.
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
588 -------------------------------------------------------------------------------
590 Optional VSC Configuration
591 ==========================
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:
608 Disable Synchronized Scrolling of Editor and Preview
609 ----------------------------------------------------
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`
617 -------------------------------------------------------------------------------
622 .. note:: This section is optional and should not be understood as a
628 Open :guilabel:`Add-Ons and Themes`, then search and install the following
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 +------------------------------+-------------------------------+
642 Install this simple editor with ...
646 sudo apt install -y retext
648 -------------------------------------------------------------------------------
653 This is a collection of helpful resources if you want to extend and deepen your
659 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
660 - `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
665 - `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
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>`__
674 Linux Foundation Release Engineering
675 ------------------------------------
677 - `LF RelEng Documentation (recommended reading) <https://docs.releng.linuxfoundation.org>`__
680 ONAP Documentation Procedures for Developers
681 --------------------------------------------
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>`__
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/>`__
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/>`__
702 ReadTheDocs Sphinx Theme
703 ------------------------
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>`__
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>`__
717 currently unavailable
718 - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
724 - `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
729 - `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
731 Visual Studio Code (VSC)
732 ------------------------
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/>`__
739 -------------------------------------------------------------------------------
744 There are still some open topics or issues in this guide. They are subject
745 for one of the upcoming releases.
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
768 - update instructions to enable use of latest reStructuredText VSC extension
771 #########################################################################
772 EMBEDDED PICTURES & ICONS BELOW
773 #########################################################################
775 .. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
778 .. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
781 .. |FileExpl| image:: ./media/files.svg
784 .. |GearSymb| image:: ./media/gear.svg