Setup of a Documentation Development System
- Release Relevance
10.x.x (Jakarta) - 6.x.x (Frankfurt)
- Last Review/Update
31/03/2022
- Initial Release
05/12/2021
- Author (Company)
Thomas Kulik (Deutsche Telekom AG)
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.
VM Configuration
Note
This section is for information only and should not be understood as a requirement.
Ubuntu Image
ubuntu-20.04.3-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 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 already installed Ubuntu packages. You may need to restart the system afterwards.
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.
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.
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.
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
.
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 important to activate the onapdocs
environment before you
continue. If not already done, activate environment with …
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.
pip3 install wheel
pip3 install lfdocs-conf
which sphinx-build
Note
The lfdocs-conf
package requires multiple, additional libraries.
They are loaded automatically.
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 Show Applications (the symbol in the bottom left corner) to find the required applications.
Open Ubuntu Software > Development, select code (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.
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 ~/environments/onapdocs
git clone --branch master https://git.onap.org/doc/ ./doc
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 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 …
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
cd ~/environments/onapdocs
git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
Start VSC in the correct directory
Start VSC (always) in the docs
directory of your repository. For the
doc
repository used in this example do this with …
cd doc
cd docs
code .
Important
Don’t forget the .
(dot) when you start Visual Studio Code.
Tip
~/environments/onapdocs/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 reStructuredText extension
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.
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.
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 symbol on the right
bottom) and select Extension Settings. A new windows in VSC shows
all the parameters. Change the following ones:
- Restructuredtext › Linter: Executable Path
/usr/bin/doc8
- Restructuredtext › Linter: Name
doc8
- 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 …
- Restructuredtext: Conf Path
${workspaceFolder}/docs
Close the Extension Settings window.
Close VSC and start it again with the code .
command.
Open a .rst file and preview it in VSC
Open .rst file
Select View > Explorer. Or use the 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.
Preview
Now select Preview To The Side (the 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 commandcode .
. Then navigate via VSC’s Explorer to the directory which contains the file you like to edit. VSC may ask you, whichconf.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 whichconf.py
is currently in use. The content ofconf.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. theconf.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
Helpful Resources
This is a collection of helpful resources if you want to extend and deepen your knowledge.
Documentation
Git
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.
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 Ctrl + Shift + X Is this a problem in the RTD theme?use
menuselection
?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
update instructions to enable use of latest reStructuredText VSC extension