.. 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 11.x.x (Kohn) Last Review/Update 2022/10/25 Initial Release 2021/12/05 Author (Company) Thomas Kulik (Deutsche Telekom AG) ------------------------------------------------------------------------------- .. contents:: Table of Contents ------------------------------------------------------------------------------- Introduction ============ This guide provides a detailed description to set up a system suitable to create, check and preview documentation locally. The targeted readership are 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. In general, 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 `__. Beginning with the 'Frankfurt' release of ONAP, the documentation structure has changed and the support of submodules was removed. Although large parts of this guide are valid for earlier releases, the relevance has been limited. 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 `Linux Foundation Release Engineering Documentation `__ and the `ONAP Developer Wiki `__ to get information about all the prerequisite details. ------------------------------------------------------------------------------- VM Configuration ================ .. note:: This section is for information only and should not be understood as a requirement. Ubuntu Image Used ----------------- +--------------------------------------+ | ubuntu-22.04.1-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 installed Ubuntu packages. You may need to restart the system afterwards. Maybe you need to force a snap-store update with the following commands: .. code-block:: bash snap-store --quit sudo snap refresh Open :guilabel:`Ubuntu Software` again and check the :guilabel:`Updates` tab for required actions. 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. ------------------------------------------------------------------------------- An older version of Ubuntu LTS (e.g. 20.4.) may need additional configuration steps for proper localization: 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:``. Choose :guilabel:`Apply` to install the additional language. Regional Formats ---------------- Continue to the :guilabel:`Regional Formats` tab. Select a :guilabel:`` 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:`` 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. ------------------------------------------------------------------------------- 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 `` ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace ```` with your user name. ------------------------------------------------------------------------------- Install python3 related packages ================================ .. important:: The main python3 package comes preinstalled with Ubuntu 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 \ build-essential \ libssl-dev \ libffi-dev \ python3-dev \ 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 \ git-review \ python-wheel-common \ python3-sphinx \ python3-doc8 \ graphviz \ docutils \ curl \ tox \ jq Check git version and the path of the sphinx-build executable with ... .. code-block:: bash git --version which sphinx-build ------------------------------------------------------------------------------- Install Visual Studio Code (VSC) and update 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:`vscode` (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. ------------------------------------------------------------------------------- Configure ssh ============= 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_{algorithm}`` and ``id_{algorithm}.pub`` .. warning:: If your ssh key has been generated using the RSA SHA-1 hash algorithm, you may experience problems when connecting to other systems. The RSA SHA-1 hash algorithm has been quickly deprecated across operating systems and SSH clients because of various security vulnerabilities, with many of these technologies now outright denying the use of this algorithm. You need to create new ssh keys using a more secure algorithm. You may try to temporarily enable the insecure RSA SHA-1 hash algorithm by adding the line ``PubkeyAcceptedKeyTypes +ssh-rsa`` to your ssh ``config`` file. .. tip:: Please refer to the `Linux Foundation Release Engineering Documentation `__ for additional information. ------------------------------------------------------------------------------- Configure git ============= Configure ``git`` and ``git-review`` with ... .. code-block:: bash git config --global user.email "" git config --global user.name "" git config --global --add gitreview.username "" git config --global gitreview.remote origin Replace ```` and ```` with your account details. .. tip:: Please refer to the `Linux Foundation Release Engineering Documentation `__ for additional information. ------------------------------------------------------------------------------- Create working directory ======================== Create the working directory ``onapdocs`` in your home directory together with a ``repos`` directory to store various projects and versions. The full path is consequently ``~/onapdocs/repos``. .. code-block:: bash cd ~ mkdir onapdocs cd onapdocs mkdir repos cd repos ------------------------------------------------------------------------------- Clone example repo (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 ~/onapdocs/repos git clone --branch master https://git.onap.org/doc/ ./doc ------------------------------------------------------------------------------- Clone example repo (LF account used) ==================================== Clone repo ---------- .. code-block:: bash cd ~/onapdocs/repos git clone ssh://@gerrit.onap.org:29418/doc ------------------------------------------------------------------------------- Install required Sphinx packages ================================ .. important:: By using ``sudo pip ...`` you will see a message saying: "*WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager*". We try to avoid this installation method in a later version of this guide. Install required Sphinx packages using the file ``requirements-docs.txt`` as an input. The file resides in the downloaded ``doc`` repository. .. code-block:: bash sudo pip install -r doc/etc/requirements-docs.txt ------------------------------------------------------------------------------- Start VSC in the correct directory ================================== Start VSC (always) in the ``docs`` directory of your repository. For the cloned ``doc`` repository used in this example do this with ... .. code-block:: bash cd doc/docs code . .. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code. .. tip:: ``~/onapdocs/repos/doc/docs`` 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:`Telemetry Settings` and turn it ``off`` in the selection field. In an older version of VSC you alternatively need to 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 them ========================================= 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. .. important:: You will experience, that VSC asks you to install additional components (e.g. Esbonio Language Server, reStructuredText Syntax Highlighting). It is important to allow VSC the installation! Please manually install ... +---------------------------------------+--------------------+------------+ | IDENTIFIER (search) | NAME | TESTED | +=======================================+====================+============+ | ms-python.python | Python | v2022.16.1 | +---------------------------------------+--------------------+------------+ | lextudio.restructuredtext | reStructuredText | v189.1.0 | +---------------------------------------+--------------------+------------+ | eamodio.gitlens | GitLens | v13.0.3 | +---------------------------------------+--------------------+------------+ | streetsidesoftware.code-spell-checker | Code Spell Checker | v2.10.1 | +---------------------------------------+--------------------+------------+ | esbenp.prettier-vscode | Prettier | v9.9.0 | +---------------------------------------+--------------------+------------+ Together with the above extensions, the following software is automatically installed ... +----------------------------+--------------------------------------+-------------+ | IDENTIFIER (search) | NAME | TESTED | +============================+======================================+=============+ | ms-python.vscode-pylance | Pylance | v2022.10.30 | +----------------------------+--------------------------------------+-------------+ | several Jupyter Extensions | Jupyter ... | ... | +----------------------------+--------------------------------------+-------------+ | snekvik.simple-rst | reStructuredText Syntax highlighting | v1.5.2 | +----------------------------+--------------------------------------+-------------+ Close VSC and restart it using the ``code .`` command. 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. Values for the following parameters need to be changed: - Restructuredtext › Linter › Doc8: Executable Path - Restructuredtext › Linter › Rst-lint: Executable Path - Restructuredtext › Linter › Rstcheck: Executable Path - Esbonio › Sphinx: Build Dir - Restructuredtext: Styles .. important:: Ensure that you are changing parameters in :guilabel:`User` Settings and :strong:`not` in :guilabel:`Workspace` Settings. :guilabel:`User` Settings are applied globally - for every running instance of VSC. .. tip:: If you experience problems adding the value to ``restructuredtext.styles`` via editing the ``settings.json`` in VSC, please use an external editor (e.g. ``vi``) to add the value. Search the following parameter in the :guilabel:`Search settings` field and add the listed values: .. list-table:: VSC User Settings for reStructuredText :header-rows: 1 * - PARAMETER (search) - VALUE * - restructuredtext.linter.doc8.executablePath - /usr/bin/doc8 * - restructuredtext.linter.rst-lint.executablePath - /usr/bin/doc8 * - restructuredtext.linter.rstcheck.executablePath - /usr/bin/doc8 * - esbonio.sphinx.buildDir - ${workspaceFolder}/_build * - restructuredtext.styles - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css Close the :guilabel:`Extension Settings` window. Close VSC and restart it using the ``code .`` command. Your VSC User Settings file ``/home//.config/Code/User/settings.json`` should now include the following entries: .. code-block:: bash { "telemetry.telemetryLevel": "off", "restructuredtext.linter.doc8.executablePath": "/usr/bin/doc8", "restructuredtext.linter.rst-lint.executablePath": "/usr/bin/doc8", "restructuredtext.linter.rstcheck.executablePath": "/usr/bin/doc8", "esbonio.sphinx.buildDir": "${workspaceFolder}/_build", "restructuredtext.styles": [ "/usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css" ] } ------------------------------------------------------------------------------- Open a .rst file and preview it in VSC ====================================== Open .rst file -------------- Select :guilabel:`View` > :guilabel:`Explorer`. Or 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. Alternatively you can open this guide and see how it looks like in the reStructuredText format. It can be found in ``docs/guides/onap-documentation`` and is named ``setup-of-a-doc-dev-system.rst``. 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. To show only problems for the :strong:`active` file in VSC, set the filter to :guilabel:`Show Active File Only`. 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. Build documentation locally --------------------------- To build documentation locally use the ``tox`` command, check the output for error messages and check the files using your favorite browser. .. code-block:: bash cd ~/onapdocs/repos/doc tox ... (checks are executed, docs are build, check logging output) ... cd docs/_build/html firefox ./index.html 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. - 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 ========================== Add 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 ] Disable Synchronized Scrolling of Editor and Preview ---------------------------------------------------- To disable the synchronized scrolling of editor and preview, open :guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and search for ``Restructuredtext › Preview: Scroll``. Then uncheck :guilabel:`Restructuredtext › Preview: Scroll Editor With Preview` and :guilabel:`Restructuredtext › Preview: Scroll Preview With Editor` ------------------------------------------------------------------------------- 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 Ubuntu Restricted Extras ------------------------ If you experience problems during playback of some audio or video formats on your system, please check the ``ubuntu-restricted-extras`` package. ------------------------------------------------------------------------------- Helpful Resources ================= This is a collection of helpful resources if you want to extend and deepen your knowledge. Documentation ------------- - `Write The Docs: Documentation Guide `__ - `Techwriter Documatt Blog `__ Gerrit ------ - `LF RelEng Gerrit Guide `_ Git/GitHub ---------- - `GitHub Authentication `__ - `How To Install Git on Ubuntu 20.04 `__ - `LF RelEng Git Guide `__ Linux Foundation Release Engineering ------------------------------------ - `LF RelEng Documentation (recommended reading) `__ ONAP Documentation Procedures for Developers -------------------------------------------- - `Procedure #1 for the ONAP Documentation Team `__ - `Procedure #2 for all other ONAP Project Teams `__ Python ------ - `Install Python for Most Features `__ - `How To Install Python 3 and Set Up a Programming Environment on an Ubuntu 20.04 Server `__ - `Using Python environments in VS Code `__ - `Getting Started with Python in VS Code `__ - `Linux Foundation Docs Conf (obsolete) `__ ReadTheDocs ----------- - `Documentation `__ - `Tutorial `__ - `GitHub `__ ReadTheDocs Sphinx Theme ------------------------ - `ReadTheDocs Sphinx Theme (recommended reading) `__ - `ReadTheDocs Sphinx Theme Configuration `__ reStructuredText ---------------- - `reStructuredText Directives `__ - `reStructuredText and Sphinx Cheat Sheet I `__ .. currently unavailable - `Online reStructuredText Editor `__ Sphinx ------ - `Sphinx Documentation Generator `__ Visual Studio Code (VSC) ------------------------ - `VSC Basic Editing `__ - `Code Formatting with Prettier in Visual Studio Code `__ - `VSC Icons `__ - `reStructuredText Extension `__ ------------------------------------------------------------------------------- Backlog ======= There are still some open topics or issues in this guide. They are subject for one of the upcoming releases. - fix issues with virtual environments using different python versions in VCS - consider ``pandoc`` in this guide? - 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) - 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