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 -------------------------------------------------------------------------------
86 .. note:: This section is for information only and should not be understood as
92 +--------------------------------------+
93 | ubuntu-20.04.3-desktop-amd64.iso |
94 +--------------------------------------+
96 Please check what image must be used for your type of hardware.
101 +-------------------------+------------+
103 +-------------------------+------------+
104 | Processors / Cores each | 2 / 2 |
105 +-------------------------+------------+
106 | Hard Disk | 64 GB |
107 +-------------------------+------------+
109 Depending on your requirements you can modify the values for virtual memory,
110 processors, cores or hard disk space.
115 Follow the instructions of your virtualization solution to install Ubuntu in a
116 virtual machine. Log in after the installation has finished.
118 -------------------------------------------------------------------------------
123 .. note:: This section is optional and should not be understood as a
129 The following actions are performed on the Ubuntu desktop. You may use the
130 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
131 the bottom left corner) to find the required applications. Later on you need to
132 start also a :guilabel:`Terminal` window from here.
137 Open :guilabel:`Software Updater` and update already installed Ubuntu packages.
138 You may need to restart the system afterwards.
143 Open :guilabel:`Language Support`. You are asked to complete the installation.
144 Select the :guilabel:`Install` button to complete. Continue in the
145 :guilabel:`Language Support` window and open
146 :guilabel:`Install / Remove Languages`. Then select your preferred
147 :guilabel:`<LANGUAGE>`. Choose :guilabel:`Apply` to install the additional
153 Continue to the :guilabel:`Regional Formats` tab. Select a
154 :guilabel:`<FORMAT>` to show e.g. date, time and numbers in your preferred
155 format. Press :guilabel:`Close` to close the window.
160 To change the keyboard layout used e.g. in command line windows, open
161 :guilabel:`Settings`. Navigate to :guilabel:`Region & Language`. At
162 :guilabel:`Input Sources` press the :guilabel:`+` sign. Select your preferred
163 :guilabel:`<INPUTSOURCE>` and use :guilabel:`Add` to add it. Move it to the top
164 of the list using drag and drop. Close the window. You may need to logout from
165 the UI and login again to make your changes effective.
170 Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
171 :guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
172 and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
175 -------------------------------------------------------------------------------
177 Disable sudo password for your user
178 ===================================
180 .. warning:: This section is optional and should not be understood as a
181 requirement. Disabling password authentication for all commands is very
182 convenient at use **but it strongly exposes your system to malicious code**.
183 For a system dedicated to development it might be OK, but not for a
184 production system! Handle with care. You have been warned.
186 Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ...
192 and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
193 ``<USER>`` with your user name.
195 -------------------------------------------------------------------------------
197 Install python3 related packages
198 ================================
200 .. note:: The main python3 package is preinstalled in Ubuntu 20.04.
202 Open a :guilabel:`Terminal` window and update the package management system
211 Install python3 related packages with ...
215 sudo apt install -y python3-pip \
223 Check the python3 version with ...
229 -------------------------------------------------------------------------------
231 Install git and documentation related packages
232 ==============================================
234 Install the required packages with ...
238 sudo apt install -y git \
246 Check the git version with ...
252 -------------------------------------------------------------------------------
254 Create virtual environment and activate
255 =======================================
257 In this guide, virtual environments are generally located in your home
258 directory under ``~/environments``. For the development of ONAP documentation
259 the virtual environment ``onapdocs`` is created. The full path is consequently
260 ``~/environments/onapdocs``.
267 python3 -m venv onapdocs
268 cd ~/environments/onapdocs
271 To indicate that you are now working in an virtual environment, the prompt of
272 your terminal has changed. Now it starts with ``(onapdocs)``.
274 -------------------------------------------------------------------------------
276 Install required Sphinx packages in activated environment (I)
277 =============================================================
279 It is :strong:`important` to activate the ``onapdocs`` environment before you
280 continue. If not already done, activate environment with ...
284 cd ~/environments/onapdocs
287 To indicate that you are now working in an virtual environment, the prompt of
288 your terminal has changed. Now it starts with ``(onapdocs)``.
290 .. important:: Now you are installing packages only for the 'onapdocs' virtual
299 .. tip:: Remember the path
300 ``/home/<USER>/environments/onapdocs/bin/sphinx-build``, you need it later
301 to configure a VSC extension.
303 -------------------------------------------------------------------------------
305 Install Visual Studio Code (VSC) and update already installed applications
306 ==========================================================================
308 The following actions are performed on the Ubuntu desktop. You may use the
309 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
310 the bottom left corner) to find the required applications.
312 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
313 :guilabel:`code` (Visual Studio Code) and press :guilabel:`Install` to install
314 the integrated development environment (IDE).
316 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
317 installed applications are up to date.
319 -------------------------------------------------------------------------------
321 Clone example repo (no LF account)
322 ==================================
327 For a quick start you can clone e.g. the ``doc`` repository even without a
328 Linux Foundation (LF) account with ...
332 cd ~/environments/onapdocs
333 git clone --branch master https://git.onap.org/doc/ ./doc
335 -------------------------------------------------------------------------------
337 Clone example repo (LF account used)
338 ====================================
340 Prerequisite configuration
341 --------------------------
343 If you plan to contribute to the ONAP community and you want to submit changes
344 to a specific project later on, please refer to the
345 `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information about all
346 the prerequisite details.
348 If you already have a LF account and you have shared your public ssh key you
349 can finalize the configuration of this development system by updating your ssh
350 configuration in the ``~/.ssh`` directory by copying over ``config``,
351 ``id_rsa`` and ``id_rsa.pub``
353 In addition you configure ``git`` and ``git-review`` with ...
357 git config --global user.email "<GIT-EMAIL>"
358 git config --global user.name "<GIT-USER>"
359 git config --global --add gitreview.username "<GIT-USER>"
360 git config --global gitreview.remote origin
362 Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
369 cd ~/environments/onapdocs
370 git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
372 -------------------------------------------------------------------------------
374 Install required Sphinx packages in activated environment (II)
375 ==============================================================
377 Continue with the installation of required packages. Use the file
378 ``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
383 cd ~/environments/onapdocs
384 sudo pip install -r doc/etc/requirements-docs.txt
386 -------------------------------------------------------------------------------
388 Start VSC in the correct directory
389 ==================================
391 Start VSC (always) in the ``docs`` directory of your repository. For the
392 ``doc`` repository used in this example do this with ...
400 .. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
402 .. tip:: ``~/environments/onapdocs/doc/docs`` is now your
403 ``${workspaceFolder}`` because you have started VSC (``code .``) from here!
405 -------------------------------------------------------------------------------
407 Disable Telemetry of VSC
408 ========================
410 In case you want to disable telemetry functionality of Visual Studio Code, open
411 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Telemetry Settings` and
412 turn it ``off`` in the selection field.
414 In an older version of VSC you alternatively need to open
415 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
416 search for ``telemetry``. Then uncheck
417 :guilabel:`Telemetry: Enable Crash Reporter` and
418 :guilabel:`Telemetry: Enable Telemetry`
420 .. warning:: Extensions may be collecting their own usage data and are not
421 controlled by the ``telemetry.enableTelemetry`` setting. Consult the
422 specific extension's documentation to learn about its telemetry
423 reporting and whether it can be disabled. See also
424 https://code.visualstudio.com/docs/getstarted/telemetry
426 -------------------------------------------------------------------------------
428 Install VSC extensions and configure reStructuredText extension
429 ===============================================================
431 Install VSC extensions
432 ----------------------
434 Extension bring additional power to Visual Studio Code. To search and install
435 them, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Extensions`
436 or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the
437 extension in the :guilabel:`Search Extensions in Marketplace` window.
438 Press :guilabel:`Install` if you have found the required extension.
442 +--------------------------------------+---------------------------------------+---------+
443 | Python | ms-python.python | latest |
444 +--------------------------------------+---------------------------------------+---------+
445 | reStructuredText | lextudio.restructuredtext | 169.0.0 |
446 +--------------------------------------+---------------------------------------+---------+
447 | reStructuredText Syntax highlighting | trond-snekvik.simple-rst | latest |
448 +--------------------------------------+---------------------------------------+---------+
449 | Code Spell Checker | streetsidesoftware.code-spell-checker | latest |
450 +--------------------------------------+---------------------------------------+---------+
451 | Prettier | esbenp.prettier-vscode | latest |
452 +--------------------------------------+---------------------------------------+---------+
453 | GitLens | eamodio.gitlens | latest |
454 +--------------------------------------+---------------------------------------+---------+
456 .. warning:: Use the reStructuredText extension version 169.0.0 or lower to
457 avoid problems with the preview. You need to downgrade after the initial
458 installation. This can be done by using
459 :guilabel:`Uninstall` > :guilabel:`Install Another Version...` in the VSC
460 extension management.
462 Configure reStructuredText extension
463 ------------------------------------
465 To configure ``reStructuredText`` extension, open :guilabel:`File` >
466 :guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut
467 ``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the
468 :guilabel:`Search Extensions in Marketplace` window. After you have found the
469 extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
470 bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
471 all the parameters. Change the following ones:
473 :strong:`Restructuredtext › Linter: Executable Path`
476 :strong:`Restructuredtext › Linter: Name`
479 :strong:`Restructuredtext: Sphinx Build Path`
480 ``/home/<USER>/environments/onapdocs/bin/sphinx-build``
482 Replace ``<USER>`` with your user name.
484 Only in case the preview creates an error message, try ...
486 :strong:`Restructuredtext: Conf Path`
487 ``${workspaceFolder}/docs``
489 Close the :guilabel:`Extension Settings` window.
491 Close VSC and start it again with the ``code .`` command.
493 -------------------------------------------------------------------------------
495 Open a .rst file and preview it in VSC
496 ======================================
501 Select :guilabel:`View` > :guilabel:`Explorer`. Or use the |FileExpl| symbol in
502 the upper left corner. Expand the ``docs`` folder by clicking on the ``>``
503 symbol. Select the file ``index.rst``. The code shows up in the right pane
506 Alternatively you can open this guide and see how it looks like in the
507 reStructuredText format. It can be found in ``docs/guides/onap-documentation``
508 and is named ``setup-of-a-doc-dev-system.rst``.
513 You may see problems with the reStructuredText markup because the code is
514 underlined in various colors. For the details select :guilabel:`View` >
515 :guilabel:`Problems` to open an additional window at the bottom of VSC.
517 When you select a specific entry in the problem list, the code window is
518 updated to show the related line in the code.
523 Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top
524 right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window
525 on the right hand side. This may take a few seconds. The preview shows up and
526 renders the ``index.rst`` as it would look like on ReadTheDocs.
531 The learnings are ...
534 - Start VSC always in the ``docs`` directory of the repository. Use the
535 command ``code .``. Then navigate via VSC's :guilabel:`Explorer`
536 |FileExpl| to the directory which contains the file you like to edit. VSC
537 may ask you, which ``conf.py`` VSC should use. Choose the one which
538 resides in the directory where you have started VSC. Check also the (blue)
539 bottom line of VSC. There you see which ``conf.py`` is currently in use.
540 The content of ``conf.py`` affects how the documentation is presented.
541 - VSC may claim that some packages require an update. This can be easily
542 fixed. VSC offers automatically to install or update the package.
543 - VSC may ask you to install ``snooty``. Please install.
544 - Select the correct environment in the (blue) bottom line
545 ``'onapdocs':venv``. Have also a view on the other interesting
546 information (e.g. the ``conf.py`` which is currently in use).
547 - First, close and reopen preview if preview is not shown properly.
548 - Second, close and reopen VSC if preview is not shown properly.
549 - Save your file if an error does not disappear after you have corrected it.
550 - You can not navigate within the document structure by clicking the links
551 in the preview. You always have to choose the correct file in the VSC
552 :guilabel:`Explorer` window.
557 Congratulations, well done! You have configured a system well suited to
558 develop ONAP documentation and to master the challenges of reStructuredText.
559 Now have a look at all the different elements of reStructuredText and learn how
560 to use them properly. Or maybe you like to do some optional configurations at
563 -------------------------------------------------------------------------------
565 Optional VSC Configuration
566 ==========================
571 To add a ruler that indicates the line end at 79 characters, open
572 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
573 ``ruler`` in the :guilabel:`Search settings` field. In
574 :guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add
575 the value ``79``. The result should look like this:
583 Disable Synchronized Scrolling of Editor and Preview
584 ----------------------------------------------------
586 To disable the synchronized scrolling of editor and preview, open
587 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
588 search for ``Restructuredtext › Preview: Scroll``. Then uncheck
589 :guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
590 :guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
592 -------------------------------------------------------------------------------
597 .. note:: This section is optional and should not be understood as a
603 Open :guilabel:`Add-Ons and Themes`, then search and install the following
606 +------------------------------+-------------------------------+
607 | I don't care about cookies | Get rid of cookie warnings. |
608 +------------------------------+-------------------------------+
609 | UBlock Origin | A wide-spectrum blocker. |
610 +------------------------------+-------------------------------+
611 | LastPass Password Manager | Used in the Linux Foundation. |
612 +------------------------------+-------------------------------+
617 Install this simple editor with ...
621 sudo apt install -y retext
623 -------------------------------------------------------------------------------
628 This is a collection of helpful resources if you want to extend and deepen your
634 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
635 - `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
640 - `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
645 - `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
646 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
648 ONAP Documentation Procedures for Developers
649 --------------------------------------------
651 - `Procedure #1 for the ONAP Documentation Team <https://wiki.onap.org/x/-IpkBg>`__
652 - `Procedure #2 for all other ONAP Project Teams <https://wiki.onap.org/x/w4IEBw>`__
657 - `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__
658 - `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>`__
659 - `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__
660 - `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
661 - `Linux Foundation Docs Conf (obsolete) <https://pypi.org/project/lfdocs-conf/>`__
666 - `Documentation <https://docs.readthedocs.io/en/stable/>`__
667 - `GitHub <https://github.com/readthedocs/readthedocs.org/>`__
669 ReadTheDocs Sphinx Theme
670 ------------------------
672 - `ReadTheDocs Sphinx Theme (Recommended Reading!) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
673 - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
678 - `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__
679 - `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
680 - `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
684 currently unavailable
685 - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
691 - `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
696 - `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
698 Visual Studio Code (VSC)
699 ------------------------
701 - `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__
702 - `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
703 - `VSC Icons <https://github.com/microsoft/vscode-icons>`__
704 - `reStructuredText Extension <https://docs.restructuredtext.net/>`__
706 -------------------------------------------------------------------------------
711 There are still some open topics or issues in this guide. They are subject
712 for one of the upcoming releases.
714 - consider ``pandoc`` in this guide?
715 - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build
716 Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives?
717 - VSC extension configuration: Difference between "Workspace" and "User"?
718 - link to full ``ssh`` install/config?
719 - link to full ``git`` install/config?
720 - how to limit line width to improve readability? setting in conf.py?
721 - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
722 :kbd:`X` Is this a problem in the RTD theme?
723 - use ``menuselection``
724 :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
725 - evaluate and add VSC extension to "draw" tables in an aided way
726 - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
727 - find the reason for VSC error message
728 ``Substitution definition "ShowApp" empty or invalid.``
729 - find the reason for VSC error message
730 ``Unexpected indentation``
731 - find a solution to wrap lines in VSC automatically (79 chars limit)
732 - evaluate ``snooty`` and describe functionality (build in? not a extension?)
733 - add a table explaining the role of installed packages/extensions in every
735 - update instructions to enable use of latest reStructuredText VSC extension
738 #########################################################################
739 EMBEDDED PICTURES & ICONS BELOW
740 #########################################################################
742 .. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
745 .. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
748 .. |FileExpl| image:: ./media/files.svg
751 .. |GearSymb| image:: ./media/gear.svg