Setup of a Documentation Development System

Release Relevance

11.x.x (Kohn)

Last Review/Update

2022/10/25

Initial Release

2021/12/05

Author (Company)

Thomas Kulik (Deutsche Telekom AG)



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 Show Applications (the ShowApp symbol in the bottom left corner) to find the required applications. Later on you need to start also a Terminal window from here.

Software Updates

Open 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:

snap-store --quit
sudo snap refresh

Open Ubuntu Software again and check the Updates tab for required actions.

Screen Lock

Open Settings. Navigate to Privacy > Screen Lock and change settings for Blank Screen Delay and 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 Language Support. You are asked to complete the installation. Select the Install button to complete. Continue in the Language Support window and open Install / Remove Languages. Then select your preferred <LANGUAGE>. Choose Apply to install the additional language.

Regional Formats

Continue to the Regional Formats tab. Select a <FORMAT> to show e.g. date, time and numbers in your preferred format. Press Close to close the window.

Input Sources

To change the keyboard layout used e.g. in command line windows, open Settings. Navigate to Region & Language. At Input Sources press the + sign. Select your preferred <INPUTSOURCE> and use 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 Terminal window and start the visudo editor with …

sudo visudo

and add <USER> ALL=(ALL) NOPASSWD:ALL to the end of the file. Replace <USER> with your user name.




Install Visual Studio Code (VSC) and update applications

The following actions are performed on the Ubuntu desktop. You may use the desktop search function Show Applications (the ShowApp symbol in the bottom left corner) to find the required applications.

Open Ubuntu Software > Development, select vscode (Visual Studio Code) and press Install to install the integrated development environment (IDE).

Open Ubuntu Software > 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 …

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 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.

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 …

cd ~/onapdocs/repos
git clone --branch master https://git.onap.org/doc/ ./doc

Clone example repo (LF account used)

Clone repo

cd ~/onapdocs/repos
git clone ssh://<GIT-USER>@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.

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 …

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 File > Preferences > Telemetry Settings and turn it off in the selection field.

In an older version of VSC you alternatively need to open File > Preferences > Settings and search for telemetry. Then uncheck Telemetry: Enable Crash Reporter and 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 File > Preferences > Extensions or use the keyboard shortcut [Ctrl+Shift+X]. Then enter the name of the extension in the Search Extensions in Marketplace window. Press 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 File > Preferences > Extensions or use the keyboard shortcut [Ctrl+Shift+X]. Then enter reStructuredText in the Search Extensions in Marketplace window. After you have found the extension press Manage (the little GearSymb symbol on the right bottom) and select 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 User Settings and not in Workspace Settings. 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 Search settings field and add the listed values:

VSC User Settings for reStructuredText

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 Extension Settings window.

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:

{
    "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 View > 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 View > 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 active file in VSC, set the filter to Show Active File Only.

Preview

Now select 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.

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 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 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 File > Preferences > Settings and enter ruler in the Search settings field. In Editor: Rulers click on Edit in settings.json and add the value 79. The result should look like this:

"editor.rulers": [
    79
]

Disable Synchronized Scrolling of Editor and Preview

To disable the synchronized scrolling of editor and preview, open File > Preferences > Settings and search for Restructuredtext Preview: Scroll. Then uncheck Restructuredtext › Preview: Scroll Editor With Preview and Restructuredtext › Preview: Scroll Preview With Editor


Miscellaneous

Note

This section is optional and should not be understood as a requirement.

Firefox Add-ons

Open 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 …

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

Gerrit

Git/GitHub

Linux Foundation Release Engineering

ONAP Documentation Procedures for Developers

Python

ReadTheDocs

ReadTheDocs Sphinx Theme

reStructuredText

Sphinx

Ubuntu

Visual Studio Code (VSC)


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 Ctrl + Shift + X Is this a problem in the RTD theme?

  • use 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