#########################################################################
Release Relevance
- 8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
+ 11.x.x (Kohn) - 10.x.x (Jakarta)
Last Review/Update
- none
+ 23/08/2022
Initial Release
05/12/2021
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
+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
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 <https://docs.onap.org>`__.
+
+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
Ubuntu Image
------------
-+----------------------------------------+
-| ubuntu-20.04.2.0-desktop-amd64.iso |
-+----------------------------------------+
++--------------------------------------+
+| ubuntu-20.04.3-desktop-amd64.iso |
++--------------------------------------+
Please check what image must be used for your type of hardware.
.. 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
+ sudo apt install -y python3-pip \
+ build-essential \
+ libssl-dev \
+ libffi-dev \
+ python3-dev \
+ python3-venv
Check the python3 version 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
+ sudo apt install -y git \
+ git-review \
+ python3-sphinx \
+ python3-doc8 \
+ curl \
+ jq \
+ tox
Check the git version with ...
-------------------------------------------------------------------------------
-Install required Sphinx packages in activated environment
-=========================================================
+Install required Sphinx packages in activated environment (I)
+=============================================================
It is :strong:`important` to activate the ``onapdocs`` environment before you
continue. If not already done, activate environment with ...
.. 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
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).
+:guilabel:`code` (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 example repo (no LF account)
+==================================
Clone repo
----------
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)
-==================================================
+Clone example repo (LF account used)
+====================================
Prerequisite configuration
--------------------------
.. code-block:: bash
cd ~/environments/onapdocs
- git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
+ git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
-Start VSC
----------
+-------------------------------------------------------------------------------
+
+Install required Sphinx packages in activated environment (II)
+==============================================================
+
+Continue with the installation of required packages. Use the file
+``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
+repository.
-Start VSC in the ``doc`` repo directory with ...
+.. code-block:: bash
+
+ cd ~/environments/onapdocs
+ 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
+``doc`` repository used in this example do this with ...
.. code-block:: bash
cd doc
+ cd docs
code .
-.. tip:: ``~/environments/onapdocs/doc`` is now your ``${workspaceFolder}``
- because you have started VSC (``code``) from here!
+.. 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!
-------------------------------------------------------------------------------
========================
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
Please install ...
-+--------------------+-----------------------------------------+
-| Python | ms-python.python |
-+--------------------+-----------------------------------------+
-| reStructuredText | lextudio.restructuredtext |
-+--------------------+-----------------------------------------+
-| Code Spell Checker | streetsidesoftware.code-spell-checker |
-+--------------------+-----------------------------------------+
-| Prettier | esbenp.prettier-vscode |
-+--------------------+-----------------------------------------+
-| GitLens | eamodio.gitlens |
-+--------------------+-----------------------------------------+
++--------------------------------------+---------------------------------------+---------+
+| 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.
Configure reStructuredText extension
------------------------------------
Close the :guilabel:`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 :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.
+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
--------------
Optional VSC Configuration
==========================
-Ruler
------
+Add Ruler
+---------
To add a ruler that indicates the line end at 79 characters, open
:guilabel:`File` > :guilabel:`Preferences` > :guilabel:`Settings` and enter
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
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. |
-+----------------------------+-------------------------------+
++------------------------------+-------------------------------+
+| 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
-------------
This is a collection of helpful resources if you want to extend and deepen your
knowledge.
+Documentation
+-------------
+
+- `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
+- `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
+
+Gerrit
+------
+
+- `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
+
+Git
+---
+
+- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
+- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
+
+ONAP Documentation Procedures for Developers
+--------------------------------------------
+
+- `Procedure #1 for the ONAP Documentation Team <https://wiki.onap.org/x/-IpkBg>`__
+- `Procedure #2 for all other ONAP Project Teams <https://wiki.onap.org/x/w4IEBw>`__
+
Python
------
- `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/>`__
+- `Linux Foundation Docs Conf (obsolete) <https://pypi.org/project/lfdocs-conf/>`__
+
+ReadTheDocs
+-----------
+
+- `Documentation <https://docs.readthedocs.io/en/stable/>`__
+- `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 Configuration <https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html>`__
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>`__
+..
+ currently unavailable
+ - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
+
+
+Sphinx
+------
+
+- `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
+
+Ubuntu
+------
+
+- `Virtualized Ubuntu Desktop Edition <https://linuxconfig.org/ubuntu-20-04-system-requirements>`__
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>`__
+- `reStructuredText Extension <https://docs.restructuredtext.net/>`__
-------------------------------------------------------------------------------
- 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?
- 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
..
#########################################################################
Code Review / doc.git / blobdiff