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 8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
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 -------------------------------------------------------------------------------
82 .. note:: This section is for information only and should not be understood as
88 +----------------------------------------+
89 | ubuntu-20.04.2.0-desktop-amd64.iso |
90 +----------------------------------------+
92 Please check what image must be used for your type of hardware.
97 +-------------------------+------------+
99 +-------------------------+------------+
100 | Processors / Cores each | 2 / 2 |
101 +-------------------------+------------+
102 | Hard Disk | 64 GB |
103 +-------------------------+------------+
105 Depending on your requirements you can modify the values for virtual memory,
106 processors, cores or hard disk space.
111 Follow the instructions of your virtualization solution to install Ubuntu in a
112 virtual machine. Log in after the installation has finished.
114 -------------------------------------------------------------------------------
119 .. note:: This section is optional and should not be understood as a
125 The following actions are performed on the Ubuntu desktop. You may use the
126 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
127 the bottom left corner) to find the required applications. Later on you need to
128 start also a :guilabel:`Terminal` window from here.
133 Open :guilabel:`Software Updater` and update already installed Ubuntu packages.
134 You may need to restart the system afterwards.
139 Open :guilabel:`Language Support`. You are asked to complete the installation.
140 Select the :guilabel:`Install` button to complete. Continue in the
141 :guilabel:`Language Support` window and open
142 :guilabel:`Install / Remove Languages`. Then select your preferred
143 :guilabel:`<LANGUAGE>`. Choose :guilabel:`Apply` to install the additional
149 Continue to the :guilabel:`Regional Formats` tab. Select a
150 :guilabel:`<FORMAT>` to show e.g. date, time and numbers in your preferred
151 format. Press :guilabel:`Close` to close the window.
156 To change the keyboard layout used e.g. in command line windows, open
157 :guilabel:`Settings`. Navigate to :guilabel:`Region & Language`. At
158 :guilabel:`Input Sources` press the :guilabel:`+` sign. Select your preferred
159 :guilabel:`<INPUTSOURCE>` and use :guilabel:`Add` to add it. Move it to the top
160 of the list using drag and drop. Close the window. You may need to logout from
161 the UI and login again to make your changes effective.
166 Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
167 :guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
168 and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
171 -------------------------------------------------------------------------------
173 Disable sudo password for your user
174 ===================================
176 .. warning:: This section is optional and should not be understood as a
177 requirement. Disabling password authentication for all commands is very
178 convenient at use **but it strongly exposes your system to malicious code**.
179 For a system dedicated to development it might be OK, but not for a
180 production system! Handle with care. You have been warned.
182 Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ...
188 and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
189 ``<USER>`` with your user name.
191 -------------------------------------------------------------------------------
193 Install python3 related packages
194 ================================
196 .. note:: The main python3 package is preinstalled in Ubuntu 20.04.
198 Open a :guilabel:`Terminal` window and update the package management system
207 Install python3 related packages with ...
211 sudo apt install -y python3-pip
212 sudo apt install -y build-essential
213 sudo apt install -y libssl-dev
214 sudo apt install -y libffi-dev
215 sudo apt install -y python3-dev
216 sudo apt install -y python3-venv
219 Check the python3 version with ...
225 -------------------------------------------------------------------------------
227 Install git and documentation related packages
228 ==============================================
230 Install the required packages with ...
234 sudo apt install -y git
235 sudo apt install -y git-review
236 sudo apt install -y python3-sphinx
237 sudo apt install -y python3-doc8
238 sudo apt install -y curl
239 sudo apt install -y jq
241 Check the git version with ...
247 -------------------------------------------------------------------------------
249 Create virtual environment and activate
250 =======================================
252 In this guide, virtual environments are generally located in your home
253 directory under ``~/environments``. For the development of ONAP documentation
254 the virtual environment ``onapdocs`` is created. The full path is consequently
255 ``~/environments/onapdocs``.
262 python3 -m venv onapdocs
263 cd ~/environments/onapdocs
266 To indicate that you are now working in an virtual environment, the prompt of
267 your terminal has changed. Now it starts with ``(onapdocs)``.
269 -------------------------------------------------------------------------------
271 Install required Sphinx packages in activated environment
272 =========================================================
274 It is :strong:`important` to activate the ``onapdocs`` environment before you
275 continue. If not already done, activate environment with ...
279 cd ~/environments/onapdocs
282 To indicate that you are now working in an virtual environment, the prompt of
283 your terminal has changed. Now it starts with ``(onapdocs)``.
285 .. important:: Now you are installing packages only for the 'onapdocs' virtual
291 pip3 install sphinx_rtd_theme
292 pip3 install sphinxcontrib-blockdiag
293 pip3 install sphinxcontrib-needs
294 pip3 install sphinxcontrib-nwdiag
295 pip3 install sphinxcontrib-seqdiag
296 pip3 install sphinxcontrib-swaggerdoc
297 pip3 install sphinxcontrib-plantuml
298 pip3 install lfdocs-conf
303 .. tip:: Remember the path
304 ``/home/<USER>/environments/onapdocs/bin/sphinx-build``, you need it later
305 to configure a VSC extension.
307 -------------------------------------------------------------------------------
309 Install Visual Studio Code (VSC) and update already installed applications
310 ==========================================================================
312 The following actions are performed on the Ubuntu desktop. You may use the
313 desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
314 the bottom left corner) to find the required applications.
316 Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
317 :guilabel:`Visual Studio Code` and press :guilabel:`Install` to install the
318 integrated development environment (IDE).
320 Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
321 installed applications are up to date.
323 -------------------------------------------------------------------------------
325 Clone example repo and start VSC (no LF account)
326 ================================================
331 For a quick start you can clone e.g. the ``doc`` repository even without a
332 Linux Foundation (LF) account with ...
336 cd ~/environments/onapdocs
337 git clone --branch master https://git.onap.org/doc/ ./doc
342 Start VSC in the ``doc`` repo directory with ...
349 .. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}``
350 because you have started VSC (``code``) from here!
352 -------------------------------------------------------------------------------
354 Clone example repo and start VSC (LF account used)
355 ==================================================
357 Prerequisite configuration
358 --------------------------
360 If you plan to contribute to the ONAP community and you want to submit changes
361 to a specific project later on, please refer to the
362 `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information about all
363 the prerequisite details.
365 If you already have a LF account and you have shared your public ssh key you
366 can finalize the configuration of this development system by updating your ssh
367 configuration in the ``~/.ssh`` directory by copying over ``config``,
368 ``id_rsa`` and ``id_rsa.pub``
370 In addition you configure ``git`` and ``git-review`` with ...
374 git config --global user.email "<GIT-EMAIL>"
375 git config --global user.name "<GIT-USER>"
376 git config --global --add gitreview.username "<GIT-USER>"
377 git config --global gitreview.remote origin
379 Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
386 cd ~/environments/onapdocs
387 git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
392 Start VSC in the ``doc`` repo directory with ...
399 .. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}``
400 because you have started VSC (``code``) from here!
402 -------------------------------------------------------------------------------
404 Disable Telemetry of VSC
405 ========================
407 In case you want to disable telemetry functionality of Visual Studio Code, open
408 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
409 search for ``telemetry``. Then uncheck
410 :guilabel:`Telemetry: Enable Crash Reporter` and
411 :guilabel:`Telemetry: Enable Telemetry`
413 .. warning:: Extensions may be collecting their own usage data and are not
414 controlled by the ``telemetry.enableTelemetry`` setting. Consult the
415 specific extension's documentation to learn about its telemetry
416 reporting and whether it can be disabled. See also
417 https://code.visualstudio.com/docs/getstarted/telemetry
419 -------------------------------------------------------------------------------
421 Install VSC extensions and configure reStructuredText extension
422 ===============================================================
424 Install VSC extensions
425 ----------------------
427 Extension bring additional power to Visual Studio Code. To search and install
428 them, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Extensions`
429 or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the
430 extension in the :guilabel:`Search Extensions in Marketplace` window.
431 Press :guilabel:`Install` if you have found the required extension.
435 +-----------------------+-----------------------------------------+
436 | Python | ms-python.python |
437 +-----------------------+-----------------------------------------+
438 | reStructuredText | lextudio.restructuredtext |
439 +-----------------------+-----------------------------------------+
440 | Code Spell Checker | streetsidesoftware.code-spell-checker |
441 +-----------------------+-----------------------------------------+
442 | Prettier | esbenp.prettier-vscode |
443 +-----------------------+-----------------------------------------+
444 | GitLens | eamodio.gitlens |
445 +-----------------------+-----------------------------------------+
447 Configure reStructuredText extension
448 ------------------------------------
450 To configure ``reStructuredText`` extension, open :guilabel:`File` >
451 :guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut
452 ``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the
453 :guilabel:`Search Extensions in Marketplace` window. After you have found the
454 extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
455 bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
456 all the parameters. Change the following ones:
458 :strong:`Restructuredtext › Linter: Executable Path`
461 :strong:`Restructuredtext › Linter: Name`
464 :strong:`Restructuredtext: Sphinx Build Path`
465 ``/home/<USER>/environments/onapdocs/bin/sphinx-build``
467 Replace ``<USER>`` with your user name.
469 Only in case the preview creates an error message, try ...
471 :strong:`Restructuredtext: Conf Path`
472 ``${workspaceFolder}/docs``
474 Close the :guilabel:`Extension Settings` window.
476 -------------------------------------------------------------------------------
478 Open a .rst file and preview it in VSC
479 ======================================
484 Select :guilabel:`View` > :guilabel:`Explorer`. Alternatively you can use the
485 |FileExpl| symbol in the upper left corner. Expand the ``docs`` folder by
486 clicking on the ``>`` symbol. Select the file ``index.rst``. The code shows up
487 in the right pane window of VSC.
492 You may see problems with the reStructuredText markup because the code is
493 underlined in various colors. For the details select :guilabel:`View` >
494 :guilabel:`Problems` to open an additional window at the bottom of VSC.
496 When you select a specific entry in the problem list, the code window is
497 updated to show the related line in the code.
502 Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top
503 right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window
504 on the right hand side. This may take a few seconds. The preview shows up and
505 renders the ``index.rst`` as it would look like on ReadTheDocs.
510 The learnings are ...
513 - Start VSC always in the ``docs`` directory of the repository. Use the
514 command ``code .``. Then navigate via VSC's :guilabel:`Explorer`
515 |FileExpl| to the directory which contains the file you like to edit. VSC
516 may ask you, which ``conf.py`` VSC should use. Choose the one which
517 resides in the directory where you have started VSC. Check also the (blue)
518 bottom line of VSC. There you see which ``conf.py`` is currently in use.
519 The content of ``conf.py`` affects how the documentation is presented.
520 - VSC may claim that some packages require an update. This can be easily
521 fixed. VSC offers automatically to install or update the package.
522 - VSC may ask you to install ``snooty``. Please install.
523 - Select the correct environment in the (blue) bottom line
524 ``'onapdocs':venv``. Have also a view on the other interesting
525 information (e.g. the ``conf.py`` which is currently in use).
526 - First, close and reopen preview if preview is not shown properly.
527 - Second, close and reopen VSC if preview is not shown properly.
528 - Save your file if an error does not disappear after you have corrected it.
529 - You can not navigate within the document structure by clicking the links
530 in the preview. You always have to choose the correct file in the VSC
531 :guilabel:`Explorer` window.
536 Congratulations, well done! You have configured a system well suited to
537 develop ONAP documentation and to master the challenges of reStructuredText.
538 Now have a look at all the different elements of reStructuredText and learn how
539 to use them properly. Or maybe you like to do some optional configurations at
542 -------------------------------------------------------------------------------
544 Optional VSC Configuration
545 ==========================
550 To add a ruler that indicates the line end at 79 characters, open
551 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
552 ``ruler`` in the :guilabel:`Search settings` field. In
553 :guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add
554 the value ``79``. The result should look like this:
562 Disable Synchronized Scrolling of Editor and Preview
563 ----------------------------------------------------
565 To disable the synchronized scrolling of editor and preview, open
566 :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and
567 search for ``Restructuredtext › Preview: Scroll``. Then uncheck
568 :guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and
569 :guilabel:`Restructuredtext › Preview: Scroll Preview With Editor`
571 -------------------------------------------------------------------------------
576 .. note:: This section is optional and should not be understood as a
582 Open :guilabel:`Add-Ons and Themes`, then search and install the following
585 +------------------------------+-------------------------------+
586 | I don't care about cookies | Get rid of cookie warnings. |
587 +------------------------------+-------------------------------+
588 | UBlock Origin | A wide-spectrum blocker. |
589 +------------------------------+-------------------------------+
590 | LastPass Password Manager | Used in the Linux Foundation. |
591 +------------------------------+-------------------------------+
596 Install this simple editor with ...
600 sudo apt install -y retext
602 -------------------------------------------------------------------------------
607 This is a collection of helpful resources if you want to extend and deepen your
613 - `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
618 - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
623 - `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__
624 - `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>`__
625 - `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__
626 - `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__
627 - `Linux Foundation Docs Conf <https://pypi.org/project/lfdocs-conf/>`__
629 ReadTheDocs Sphinx Theme
630 ------------------------
632 - `ReadTheDocs Sphinx Theme (Recommended Reading!) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__
633 - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
638 - `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__
639 - `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
640 - `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__
641 - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
646 - `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
648 Visual Studio Code (VSC)
649 ------------------------
651 - `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__
652 - `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__
653 - `VSC Icons <https://github.com/microsoft/vscode-icons>`__
655 -------------------------------------------------------------------------------
660 There are still some open topics or issues in this guide. They are subject
661 for one of the upcoming releases.
663 - consider ``pandoc`` in this guide?
664 - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build
665 Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives?
666 - link to full ``ssh`` install/config?
667 - link to full ``git`` install/config?
668 - how to limit line width to improve readability? setting in conf.py?
669 - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
670 :kbd:`X` Is this a problem in the RTD theme?
671 - use ``menuselection``
672 :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
673 - evaluate and add VSC extension to "draw" tables in an aided way
674 - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
675 - find the reason for VSC error message
676 ``Substitution definition "ShowApp" empty or invalid.``
677 - find the reason for VSC error message
678 ``Unexpected indentation``
679 - find a solution to wrap lines in VSC automatically (79 chars limit)
680 - evaluate ``snooty`` and describe functionality (build in? not a extension?)
681 - add a table explaining the role of installed packages/extensions in every
685 #########################################################################
686 EMBEDDED PICTURES & ICONS BELOW
687 #########################################################################
689 .. |ShowApp| image:: ./media/view-app-grid-symbolic.svg
692 .. |Preview| image:: ./media/PreviewOnRightPane_16x.svg
695 .. |FileExpl| image:: ./media/files.svg
698 .. |GearSymb| image:: ./media/gear.svg