#########################################################################
Release Relevance
- 8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
+ 9.0.0 (Istanbul) - 6.0.0 (Frankfurt)
Last Review/Update
- none
+ 10/05/2021
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
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
+.. 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.
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
--------------------------
cd ~/environments/onapdocs
git clone --recurse-submodules ssh://<GIT-USER>@gerrit.onap.org:29418/doc
-Start VSC
----------
+-------------------------------------------------------------------------------
-Start VSC in the ``doc`` repo directory with ...
+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!
-------------------------------------------------------------------------------
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 |
++-----------------------+-----------------------------------------+
+| reStructuredText | lextudio.restructuredtext |
++-----------------------+-----------------------------------------+
+| Code Spell Checker | streetsidesoftware.code-spell-checker |
++-----------------------+-----------------------------------------+
+| Prettier | esbenp.prettier-vscode |
++-----------------------+-----------------------------------------+
+| GitLens | eamodio.gitlens |
++-----------------------+-----------------------------------------+
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>`__
+
+Git
+---
+
+- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
+
Python
------
- `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/>`__
+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 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
-------------------------
+Sphinx
+------
-- `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>`__
+- `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)
------------------------
- `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>`__
-
-------------------------------------------------------------------------------
Backlog
Code Review / doc.git / blobdiff