diff options
Diffstat (limited to 'docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst')
| -rw-r--r-- | docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst | 684 |
1 files changed, 684 insertions, 0 deletions
diff --git a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst new file mode 100644 index 000000000..be2d29072 --- /dev/null +++ b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst @@ -0,0 +1,684 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International +.. License. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2021 Deutsche Telekom AG + + + +******************************************* +Setup of a Documentation Development System +******************************************* + + +.. + ######################################################################### + HOW TO FILL THIS SECTION: + + Release Relevance + Name the ONAP release(s) where this document has a relevance. + ONAP release number (ONAP release name starting with a capital letter) + Examples: + 8.0.0 (Honolulu) - 1.0.0 (Amsterdam) + 7.0.1 (Guilin) - 3.0.0 (Casablanca), 1.0.0 (Amsterdam) + + Last Review/Update + Date of last review and/or update of this document. + Add "none" for a new document. Add concrete date if reviewed/updated. + Use en-US format (mm/dd/yyyy). + + Initial Release + Initial release date of this document. + Use en-US format (mm/dd/yyyy). + + Author (Company) + Name of the author and company name. Use comma to separate. + Example: + Jane Doe (ACME), John Doe (ACME) + + ! PLEASE DO NOT CHANGE THE STRUCTURE OF THIS SECTION. + ! PLEASE ADD ONLY REQUESTED INFORMATION BELOW! + ######################################################################### + +Release Relevance + 8.0.0 (Honolulu) - 1.0.0 (Amsterdam) + +Last Review/Update + none + +Initial Release + 05/12/2021 + +Author (Company) + Thomas Kulik (Deutsche Telekom AG) + +------------------------------------------------------------------------------- + +.. contents:: Table of Contents + +------------------------------------------------------------------------------- + +Introduction +============ + +Formal ONAP documentation uses the reStructuredText markup language and the +files have an ``.rst`` extension. They are part of almost every ONAP project +and can be found in the ``docs`` directory. The files are automatically +processed and you find the final ONAP documentation build hosted on +`ReadTheDocs <https://docs.onap.org>`__. + +This guide provides a detailed description to set up a system suitable to +create, check and preview documentation locally. The targeted readership is +beginners and people interested in creating documentation. + +The guide describes the setup of a development system from scratch using the +Ubuntu Desktop version installed in a virtual machine. It includes all required +steps and also some optional ones that may ease your daily work with this +development system. Feel free to adapt it to your needs. + +------------------------------------------------------------------------------- + +VM Configuration +================ + +.. note:: This section is for information only and should not be understood as + a requirement. + +Ubuntu Image +------------ + ++----------------------------------------+ +| ubuntu-20.04.2.0-desktop-amd64.iso | ++----------------------------------------+ + +Please check what image must be used for your type of hardware. + +VM Configuration +---------------- + ++-------------------------+------------+ +| Memory | 8 GB | ++-------------------------+------------+ +| Processors / Cores each | 2 / 2 | ++-------------------------+------------+ +| Hard Disk | 64 GB | ++-------------------------+------------+ + +Depending on your requirements you can modify the values for virtual memory, +processors, cores or hard disk space. + +VM Setup +-------- + +Follow the instructions of your virtualization solution to install Ubuntu in a +virtual machine. Log in after the installation has finished. + +------------------------------------------------------------------------------- + +Ubuntu Configuration +==================== + +.. note:: This section is optional and should not be understood as a + requirement. + +Finding Applications +-------------------- + +The following actions are performed on the Ubuntu desktop. You may use the +desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in +the bottom left corner) to find the required applications. Later on you need to +start also a :guilabel:`Terminal` window from here. + +Software Updates +---------------- + +Open :guilabel:`Software Updater` and update already installed Ubuntu packages. +You may need to restart the system afterwards. + +Language Support +---------------- + +Open :guilabel:`Language Support`. You are asked to complete the installation. +Select the :guilabel:`Install` button to complete. Continue in the +:guilabel:`Language Support` window and open +:guilabel:`Install / Remove Languages`. Then select your preferred +:guilabel:`<LANGUAGE>`. Choose :guilabel:`Apply` to install the additional +language. + +Regional Formats +---------------- + +Continue to the :guilabel:`Regional Formats` tab. Select a +:guilabel:`<FORMAT>` to show e.g. date, time and numbers in your preferred +format. Press :guilabel:`Close` to close the window. + +Input Sources +------------- + +To change the keyboard layout used e.g. in command line windows, open +:guilabel:`Settings`. Navigate to :guilabel:`Region & Language`. At +:guilabel:`Input Sources` press the :guilabel:`+` sign. Select your preferred +:guilabel:`<INPUTSOURCE>` and use :guilabel:`Add` to add it. Move it to the top +of the list using drag and drop. Close the window. You may need to logout from +the UI and login again to make your changes effective. + +Screen Lock +----------- + +Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` > +:guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay` +and :guilabel:`Automatic Screen Lock` to values of your choice. Close the +window. + +------------------------------------------------------------------------------- + +Disable sudo password for your user +=================================== + +.. warning:: This section is optional and should not be understood as a + requirement. Disabling password authentication for all commands is very + convenient at use **but it strongly exposes your system to malicious code**. + For a system dedicated to development it might be OK, but not for a + production system! Handle with care. You have been warned. + +Open a :guilabel:`Terminal` window and start the ``visudo`` editor with ... + +.. code-block:: bash + + sudo visudo + +and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace +``<USER>`` with your user name. + +------------------------------------------------------------------------------- + +Install python3 related packages +================================ + +.. note:: The main python3 package is preinstalled in Ubuntu 20.04. + +Open a :guilabel:`Terminal` window and update the package management system +with ... + +.. code-block:: bash + + cd ~ + sudo apt update + sudo apt -y upgrade + +Install python3 related packages with ... + +.. code-block:: bash + + sudo apt install -y python3-pip + sudo apt install -y build-essential + sudo apt install -y libssl-dev + sudo apt install -y libffi-dev + sudo apt install -y python3-dev + sudo apt install -y python3-venv + + +Check the python3 version with ... + +.. code-block:: bash + + python3 -V + +------------------------------------------------------------------------------- + +Install git and documentation related packages +============================================== + +Install the required packages with ... + +.. code-block:: bash + + sudo apt install -y git + sudo apt install -y git-review + sudo apt install -y python3-sphinx + sudo apt install -y python3-doc8 + sudo apt install -y curl + sudo apt install -y jq + +Check the git version with ... + +.. code-block:: bash + + git --version + +------------------------------------------------------------------------------- + +Create virtual environment and activate +======================================= + +In this guide, virtual environments are generally located in your home +directory under ``~/environments``. For the development of ONAP documentation +the virtual environment ``onapdocs`` is created. The full path is consequently +``~/environments/onapdocs``. + +.. code-block:: bash + + cd ~ + mkdir environments + cd ~/environments + python3 -m venv onapdocs + cd ~/environments/onapdocs + source bin/activate + +To indicate that you are now working in an virtual environment, the prompt of +your terminal has changed. Now it starts with ``(onapdocs)``. + +------------------------------------------------------------------------------- + +Install required Sphinx packages in activated environment +========================================================= + +It is :strong:`important` to activate the ``onapdocs`` environment before you +continue. If not already done, activate environment with ... + +.. code-block:: bash + + cd ~/environments/onapdocs + source bin/activate + +To indicate that you are now working in an virtual environment, the prompt of +your terminal has changed. Now it starts with ``(onapdocs)``. + +.. important:: Now you are installing packages only for the 'onapdocs' virtual + environment. + +.. code-block:: bash + + pip3 install wheel + pip3 install sphinx_rtd_theme + pip3 install sphinxcontrib-blockdiag + pip3 install sphinxcontrib-needs + pip3 install sphinxcontrib-nwdiag + pip3 install sphinxcontrib-seqdiag + pip3 install sphinxcontrib-swaggerdoc + pip3 install sphinxcontrib-plantuml + pip3 install lfdocs-conf + + which sphinx-build + +.. tip:: Remember the path + ``/home/<USER>/environments/onapdocs/bin/sphinx-build``, you need it later + to configure a VSC extension. + +------------------------------------------------------------------------------- + +Install Visual Studio Code (VSC) and update already installed applications +========================================================================== + +The following actions are performed on the Ubuntu desktop. You may use the +desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in +the bottom left corner) to find the required applications. + +Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select +:guilabel:`Visual Studio Code` and press :guilabel:`Install` to install the +integrated development environment (IDE). + +Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your +installed applications are up to date. + +------------------------------------------------------------------------------- + +Clone example repo and start VSC (no LF account) +================================================ + +Clone repo +---------- + +For a quick start you can clone e.g. the ``doc`` repository even without a +Linux Foundation (LF) account with ... + +.. code-block:: bash + + cd ~/environments/onapdocs + git clone --branch master https://git.onap.org/doc/ ./doc + +Start VSC +--------- + +Start VSC in the ``doc`` repo directory with ... + +.. code-block:: bash + + cd doc + code . + +.. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}`` + because you have started VSC (``code``) from here! + +------------------------------------------------------------------------------- + +Clone example repo and start VSC (LF account used) +================================================== + +Prerequisite configuration +-------------------------- + +If you plan to contribute to the ONAP community and you want to submit changes +to a specific project later on, please refer to the +`ONAP Developer Wiki <https://wiki.onap.org>`__ to get information about all +the prerequisite details. + +If you already have a LF account and you have shared your public ssh key you +can finalize the configuration of this development system by updating your ssh +configuration in the ``~/.ssh`` directory by copying over ``config``, +``id_rsa`` and ``id_rsa.pub`` + +In addition you configure ``git`` and ``git-review`` with ... + +.. code-block:: bash + + git config --global user.email "<GIT-EMAIL>" + git config --global user.name "<GIT-USER>" + git config --global --add gitreview.username "<GIT-USER>" + git config --global gitreview.remote origin + +Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details. + +Clone repo +---------- + +.. code-block:: bash + + cd ~/environments/onapdocs + git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc + +Start VSC +--------- + +Start VSC in the ``doc`` repo directory with ... + +.. code-block:: bash + + cd doc + code . + +.. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}`` + because you have started VSC (``code``) from here! + +------------------------------------------------------------------------------- + +Disable Telemetry of VSC +======================== + +In case you want to disable telemetry functionality of Visual Studio Code, open +:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and +search for ``telemetry``. Then uncheck +:guilabel:`Telemetry: Enable Crash Reporter` and +:guilabel:`Telemetry: Enable Telemetry` + +.. warning:: Extensions may be collecting their own usage data and are not + controlled by the ``telemetry.enableTelemetry`` setting. Consult the + specific extension's documentation to learn about its telemetry + reporting and whether it can be disabled. See also + https://code.visualstudio.com/docs/getstarted/telemetry + +------------------------------------------------------------------------------- + +Install VSC extensions and configure reStructuredText extension +=============================================================== + +Install VSC extensions +---------------------- + +Extension bring additional power to Visual Studio Code. To search and install +them, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Extensions` +or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the +extension in the :guilabel:`Search Extensions in Marketplace` window. +Press :guilabel:`Install` if you have found the required extension. + +Please install ... + ++--------------------+-----------------------------------------+ +| Python | ms-python.python | ++--------------------+-----------------------------------------+ +| reStructuredText | lextudio.restructuredtext | ++--------------------+-----------------------------------------+ +| Code Spell Checker | streetsidesoftware.code-spell-checker | ++--------------------+-----------------------------------------+ +| Prettier | esbenp.prettier-vscode | ++--------------------+-----------------------------------------+ +| GitLens | eamodio.gitlens | ++--------------------+-----------------------------------------+ + +Configure reStructuredText extension +------------------------------------ + +To configure ``reStructuredText`` extension, open :guilabel:`File` > +:guilabel:`Preferences` > :guilabel:`Extensions` or use the keyboard shortcut +``[Ctrl+Shift+X]``. Then enter ``reStructuredText`` in the +:guilabel:`Search Extensions in Marketplace` window. After you have found the +extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right +bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows +all the parameters. Change the following ones: + + :strong:`Restructuredtext › Linter: Executable Path` + ``/usr/bin/doc8`` + + :strong:`Restructuredtext › Linter: Name` + ``doc8`` + + :strong:`Restructuredtext: Sphinx Build Path` + ``/home/<USER>/environments/onapdocs/bin/sphinx-build`` + +Replace ``<USER>`` with your user name. + +Only in case the preview creates an error message, try ... + + :strong:`Restructuredtext: Conf Path` + ``${workspaceFolder}/docs`` + +Close the :guilabel:`Extension Settings` window. + +------------------------------------------------------------------------------- + +Open a .rst file and preview it in VSC +====================================== + +Open .rst file +-------------- + +Select :guilabel:`View` > :guilabel:`Explorer`. Alternatively you can use the +|FileExpl| symbol in the upper left corner. Expand the ``docs`` folder by +clicking on the ``>`` symbol. Select the file ``index.rst``. The code shows up +in the right pane window of VSC. + +Problem Window +-------------- + +You may see problems with the reStructuredText markup because the code is +underlined in various colors. For the details select :guilabel:`View` > +:guilabel:`Problems` to open an additional window at the bottom of VSC. + +When you select a specific entry in the problem list, the code window is +updated to show the related line in the code. + +Preview +------- + +Now select :guilabel:`Preview To The Side` (the |Preview| symbol on the top +right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window +on the right hand side. This may take a few seconds. The preview shows up and +renders the ``index.rst`` as it would look like on ReadTheDocs. + +Tips and Tricks +--------------- + +The learnings are ... + +.. tip:: + - Start VSC always in the ``docs`` directory of the repository. Use the + command ``code .``. Then navigate via VSC's :guilabel:`Explorer` + |FileExpl| to the directory which contains the file you like to edit. VSC + may ask you, which ``conf.py`` VSC should use. Choose the one which + resides in the directory where you have started VSC. Check also the (blue) + bottom line of VSC. There you see which ``conf.py`` is currently in use. + The content of ``conf.py`` affects how the documentation is presented. + - VSC may claim that some packages require an update. This can be easily + fixed. VSC offers automatically to install or update the package. + - VSC may ask you to install ``snooty``. Please install. + - Select the correct environment in the (blue) bottom line + ``'onapdocs':venv``. Have also a view on the other interesting + information (e.g. the ``conf.py`` which is currently in use). + - First, close and reopen preview if preview is not shown properly. + - Second, close and reopen VSC if preview is not shown properly. + - Save your file if an error does not disappear after you have corrected it. + - You can not navigate within the document structure by clicking the links + in the preview. You always have to choose the correct file in the VSC + :guilabel:`Explorer` window. + +That's it! +---------- + +Congratulations, well done! You have configured a system well suited to +develop ONAP documentation and to master the challenges of reStructuredText. +Now have a look at all the different elements of reStructuredText and learn how +to use them properly. Or maybe you like to do some optional configurations at +your system first. + +------------------------------------------------------------------------------- + +Optional VSC Configuration +========================== + +Ruler +----- + +To add a ruler that indicates the line end at 79 characters, open +:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter +``ruler`` in the :guilabel:`Search settings` field. In +:guilabel:`Editor: Rulers` click on :guilabel:`Edit in settings.json` and add +the value ``79``. The result should look like this: + +.. code-block:: bash + + "editor.rulers": [ + 79 + ] + +------------------------------------------------------------------------------- + +Miscellaneous +============= + +.. note:: This section is optional and should not be understood as a + requirement. + +Firefox Add-ons +--------------- + +Open :guilabel:`Add-Ons and Themes`, then search and install the following +add-ons: + ++----------------------------+-------------------------------+ +| I don't care about cookies | Get rid of cookie warnings. | ++----------------------------+-------------------------------+ +| UBlock Origin | A wide-spectrum blocker. | ++----------------------------+-------------------------------+ +| LastPass Password Manager | Used in the Linux Foundation. | ++----------------------------+-------------------------------+ + +ReText Editor +------------- + +Install this simple editor with ... + +.. code-block:: bash + + sudo apt install -y retext + +------------------------------------------------------------------------------- + +Helpful Resources +================= + +This is a collection of helpful resources if you want to extend and deepen your +knowledge. + +Python +------ + +- `Install Python for Most Features <https://docs.restructuredtext.net/articles/prerequisites.html#install-python-for-most-features>`__ +- `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>`__ +- `Using Python environments in VS Code <https://code.visualstudio.com/docs/python/environments>`__ +- `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`__ +- `Linux Foundation Docs Conf <https://pypi.org/project/lfdocs-conf/>`__ + +reStructuredText +---------------- + +- `reStructuredText Directives <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__ +- `reStructuredText and Sphinx Cheat Sheet I <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__ +- `reStructuredText and Sphinx Cheat Sheet II <https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html>`__ +- `Online reStructuredText Editor <http://rst.ninjs.org/#>`__ + +ReadTheDocs Sphinx Theme +------------------------ + +- `ReadTheDocs Sphinx Theme (highly recommended) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__ +- `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__ + +Visual Studio Code (VSC) +------------------------ + +- `VSC Basic Editing <https://code.visualstudio.com/docs/editor/codebasics>`__ +- `Code Formatting with Prettier in Visual Studio Code <https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code>`__ +- `VSC Icons <https://github.com/microsoft/vscode-icons>`__ + +Git +--- + +- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__ + +Documentation +------------- + +- `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__ + +------------------------------------------------------------------------------- + +Backlog +======= + +There are still some open topics or issues in this guide. They are subject +for one of the upcoming releases. + + - consider ``pandoc`` in this guide? + - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build + Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives? + - link to full ``ssh`` install/config? + - link to full ``git`` install/config? + - how to limit line width to improve readability? setting in conf.py? + - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` + + :kbd:`X` Is this a problem in the RTD theme? + - use ``menuselection`` + :menuselection:`My --> Software --> Some menu --> Some sub menu 1`? + - evaluate and add VSC extension to "draw" tables in an aided way + - add infos for config files, e.g. ``conf.py``, ``conf.yaml`` + - find the reason for VSC error message + ``Substitution definition "ShowApp" empty or invalid.`` + - find the reason for VSC error message + ``Unexpected indentation`` + - find a solution to wrap lines in VSC automatically (79 chars limit) + - evaluate ``snooty`` and describe functionality (build in? not a extension?) + - add a table explaining the role of installed packages/extensions in every + section + +.. + ######################################################################### + EMBEDDED PICTURES & ICONS BELOW + ######################################################################### + +.. |ShowApp| image:: ./media/view-app-grid-symbolic.svg + :width: 20 + +.. |Preview| image:: ./media/PreviewOnRightPane_16x.svg + :width: 20 + +.. |FileExpl| image:: ./media/files.svg + :width: 20 + +.. |GearSymb| image:: ./media/gear.svg + :width: 20 |