#########################################################################
Release Relevance
- 8.0.0 (Honolulu) - 1.0.0 (Amsterdam)
+ 10.x.x (Jakarta) - 6.x.x (Frankfurt)
Last Review/Update
- 06/02/2021
+ 31/03/2022
Initial Release
05/12/2021
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
- pip3 install pylint
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 correct directory
+==================================
-Start VSC in the ``doc`` repo directory with ...
+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.
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
--------------
-------------
- `Write The Docs: Documentation Guide <https://www.writethedocs.org/guide>`__
+- `Techwriter Documatt Blog <https://techwriter.documatt.com/>`__
Git
---
- `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
+-----------
+
+- `Documentation <https://docs.readthedocs.io/en/stable/>`__
+- `GitHub <https://github.com/readthedocs/readthedocs.org/>`__
+
ReadTheDocs Sphinx Theme
------------------------
- `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/#>`__
+
+
+..
+ currently unavailable
+ - `Online reStructuredText Editor <http://rst.ninjs.org/#>`__
+
+
+Sphinx
+------
+
+- `Sphinx Documentation Generator <https://www.sphinx-doc.org/en/master/>`__
Ubuntu
------
- `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>`__
+- `reStructuredText Extension <https://docs.restructuredtext.net/>`__
-------------------------------------------------------------------------------
- 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