diff options
| -rw-r--r-- | docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst | 333 |
1 files changed, 204 insertions, 129 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 index 6b43ec82b..f02851abf 100644 --- a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst +++ b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst @@ -42,7 +42,7 @@ Release Relevance 11.x.x (Kohn) - 10.x.x (Jakarta) Last Review/Update - 2022/09/01 + 2022/09/06 Initial Release 2021/12/05 @@ -78,6 +78,12 @@ 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 <https://docs.releng.linuxfoundation.org/>`__ +and the `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information +about all the prerequisite details. + ------------------------------------------------------------------------------- VM Configuration @@ -90,7 +96,7 @@ Ubuntu Image ------------ +--------------------------------------+ -| ubuntu-20.04.3-desktop-amd64.iso | +| ubuntu-22.04.1-desktop-amd64.iso | +--------------------------------------+ Please check what image must be used for your type of hardware. @@ -134,9 +140,22 @@ start also a :guilabel:`Terminal` window from here. Software Updates ---------------- -Open :guilabel:`Software Updater` and update already installed Ubuntu packages. +Open :guilabel:`Software Updater` and update installed Ubuntu packages. You may need to restart the system afterwards. +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 ---------------- @@ -164,14 +183,6 @@ To change the keyboard layout used e.g. in command line windows, open 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 @@ -197,7 +208,8 @@ and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace Install python3 related packages ================================ -.. note:: The main python3 package is preinstalled in Ubuntu 20.04. +.. important:: The main python3 package is preinstalled in Ubuntu. But please + ensure that you are using python version 3.8 or higher. Open a :guilabel:`Terminal` window and update the package management system with ... @@ -239,11 +251,12 @@ Install the required packages with ... git-review \ python3-sphinx \ python3-doc8 \ + docutils \ curl \ jq \ tox -Check the git version and the path of the sphinx-build executable ... +Check git version and the path of the sphinx-build executable with ... .. code-block:: bash @@ -251,71 +264,89 @@ Check the git version and the path of the sphinx-build executable ... which sphinx-build +------------------------------------------------------------------------------- -.. tip:: Remember the path - ``/usr/bin/sphinx-build``, you need it later - to configure a VSC extension. +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. -Create virtual environment and activate -======================================= +Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select +:guilabel:`vscode` (Visual Studio Code) and press :guilabel:`Install` to +install the integrated development environment (IDE). -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``. +Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your +installed applications are up to date. -.. code-block:: bash +------------------------------------------------------------------------------- - cd ~ - mkdir environments - cd ~/environments - python3 -m venv onapdocs - cd ~/environments/onapdocs - source bin/activate +Configure ssh +============= -To indicate that you are now working in an virtual environment, the prompt of -your terminal has changed. Now it starts with ``(onapdocs)``. +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. -Install required Sphinx packages in activated environment (I) -============================================================= + 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. -It is :strong:`important` to activate the ``onapdocs`` environment before you -continue. If not already done, activate environment with ... + 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. -.. code-block:: bash +.. tip:: Please refer to the + `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__ + for additional information. - 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)``. +Configure git +============= -.. important:: Now you are installing packages only for the 'onapdocs' virtual - environment. +Configure ``git`` and ``git-review`` with ... .. code-block:: bash - pip3 install wheel + 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. + +.. tip:: Please refer to the + `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__ + for additional information. ------------------------------------------------------------------------------- -Install Visual Studio Code (VSC) and update already installed applications -========================================================================== +Create virtual environment and activate +======================================= -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. +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``. -Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select -:guilabel:`code` (Visual Studio Code) and press :guilabel:`Install` to install -the integrated development environment (IDE). +.. code-block:: bash -Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your -installed applications are up to date. + 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)``. ------------------------------------------------------------------------------- @@ -338,42 +369,36 @@ Linux Foundation (LF) account with ... Clone example repo (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 ... +Clone repo +---------- .. 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 + cd ~/environments/onapdocs + git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc -Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details. +------------------------------------------------------------------------------- -Clone repo ----------- +Install required Sphinx packages in activated environment +========================================================= + +It is :strong:`important` to work in the ``onapdocs`` virtual environment. If +not already done, activate environment with ... .. code-block:: bash cd ~/environments/onapdocs - git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc + 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. -Install required Sphinx packages in activated environment (II) -============================================================== +.. code-block:: bash + + pip3 install wheel Continue with the installation of required packages. Use the file ``requirements-docs.txt`` for it. The file resides in the downloaded ``doc`` @@ -394,8 +419,7 @@ Start VSC (always) in the ``docs`` directory of your repository. For the .. code-block:: bash - cd doc - cd docs + cd doc/docs code . .. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code. @@ -426,8 +450,8 @@ search for ``telemetry``. Then uncheck ------------------------------------------------------------------------------- -Install VSC extensions and configure reStructuredText extension -=============================================================== +Install VSC extensions and configure them +========================================= Install VSC extensions ---------------------- @@ -440,25 +464,24 @@ Press :guilabel:`Install` if you have found the required extension. Please install ... -+--------------------------------------+---------------------------------------+---------+ -| Python | ms-python.python | latest | -+--------------------------------------+---------------------------------------+---------+ -| reStructuredText | lextudio.restructuredtext | 169.0.0 | -+--------------------------------------+---------------------------------------+---------+ -| reStructuredText Syntax highlighting | trond-snekvik.simple-rst | latest | -+--------------------------------------+---------------------------------------+---------+ -| Code Spell Checker | streetsidesoftware.code-spell-checker | latest | -+--------------------------------------+---------------------------------------+---------+ -| Prettier | esbenp.prettier-vscode | latest | -+--------------------------------------+---------------------------------------+---------+ -| GitLens | eamodio.gitlens | latest | -+--------------------------------------+---------------------------------------+---------+ - -.. warning:: Use the reStructuredText extension version 169.0.0 or lower to - avoid problems with the preview. You need to downgrade after the initial - installation. This can be done by using - :guilabel:`Uninstall` > :guilabel:`Install Another Version...` in the VSC - extension management. ++---------------------------------------+--------------------------------------+-------------+ +| IDENTIFIER (search) | NAME | TESTED | ++=======================================+======================================+=============+ +| ms-python.python | Python | v2022.14.0 | ++---------------------------------------+--------------------------------------+-------------+ +| lextudio.restructuredtext | reStructuredText | v189.1.0 | ++---------------------------------------+--------------------------------------+-------------+ +| trond-snekvik.simple-rst | reStructuredText Syntax highlighting | v1.5.2 | ++---------------------------------------+--------------------------------------+-------------+ +| eamodio.gitlens | GitLens | v12.2.1 | ++---------------------------------------+--------------------------------------+-------------+ +| streetsidesoftware.code-spell-checker | Code Spell Checker | v2.7.2 | ++---------------------------------------+--------------------------------------+-------------+ + +Close VSC and restart it using the ``code .`` command. + +You may experience, that VSC asks you to install additional components +(e.g. the Esbonio Language Server). Please allow VSC to install them. Configure reStructuredText extension ------------------------------------ @@ -469,27 +492,78 @@ To configure ``reStructuredText`` extension, open :guilabel:`File` > :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: +all the parameters. + +We need to change values for ... + +``Restructuredtext › Linter › Doc8: Executable Path`` + +``Restructuredtext › Linter › Rst-lint: Executable Path`` + +``Restructuredtext › Linter › Rstcheck: Executable Path`` - :strong:`Restructuredtext › Linter: Executable Path` - ``/usr/bin/doc8`` +``Esbonio › Sphinx: Build Dir`` - :strong:`Restructuredtext › Linter: Name` - ``doc8`` +``Esbonio › Sphinx: Conf Dir`` - :strong:`Restructuredtext: Sphinx Build Path` - ``/usr/bin/sphinx-build`` +``Esbonio › Sphinx: Src Dir`` -Replace ``<USER>`` with your user name. +``Restructuredtext: Styles`` -Only in case the preview creates an error message, try ... - :strong:`Restructuredtext: Conf Path` - ``${workspaceFolder}/docs`` +.. 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 + * - restructuredtext.styles + - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css + * - esbonio.sphinx.buildDir + - ${workspaceFolder}/_build/html + * - esbonio.sphinx.confDir + - ${workspaceFolder} + * - esbonio.sphinx.srcDir + - ${workspaceFolder} + Close the :guilabel:`Extension Settings` window. -Close VSC and start it again with the ``code .`` command. +Close VSC and restart it using the ``code .`` command. + +Your VSC User Settings file ``/home/<USER>/.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", + "restructuredtext.styles": [ + /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css + ] + "esbonio.sphinx.buildDir": "${workspaceFolder}/_build/html", + "esbonio.sphinx.confDir": "${workspaceFolder}", + "esbonio.sphinx.srcDir": "${workspaceFolder}" + ------------------------------------------------------------------------------- @@ -516,7 +590,9 @@ 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. +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 ------- @@ -541,7 +617,6 @@ The learnings are ... 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). @@ -640,11 +715,18 @@ Gerrit - `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_ -Git ---- +Git/GitHub +---------- -- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__ +- `GitHub Authentication <https://docs.github.com/en/authentication>`__ - `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__ +- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__ + +Linux Foundation Release Engineering +------------------------------------ + +- `LF RelEng Documentation (recommended reading) <https://docs.releng.linuxfoundation.org>`__ + ONAP Documentation Procedures for Developers -------------------------------------------- @@ -665,12 +747,13 @@ ReadTheDocs ----------- - `Documentation <https://docs.readthedocs.io/en/stable/>`__ +- `Tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`__ - `GitHub <https://github.com/readthedocs/readthedocs.org/>`__ ReadTheDocs Sphinx Theme ------------------------ -- `ReadTheDocs Sphinx Theme (Recommended Reading!) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__ +- `ReadTheDocs Sphinx Theme (recommended reading) <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`__ - `ReadTheDocs Sphinx Theme Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__ reStructuredText @@ -713,12 +796,6 @@ 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? - - VSC extension configuration: Difference between "Workspace" and "User"? - - 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`` @@ -730,10 +807,8 @@ for one of the upcoming releases. - 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 - - update instructions to enable use of latest reStructuredText VSC extension .. ######################################################################### |