#########################################################################
Release Relevance
- 9.0.0 (Istanbul) - 6.0.0 (Frankfurt)
+ 11.x.x (Kohn) - 10.x.x (Jakarta)
Last Review/Update
- 10/05/2021
+ 23/08/2022
Initial Release
05/12/2021
.. 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 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.
.. 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
+
+-------------------------------------------------------------------------------
+
+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.
+
+.. code-block:: bash
+
+ cd ~/environments/onapdocs
+ sudo pip install -r doc/etc/requirements-docs.txt
-------------------------------------------------------------------------------
========================
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
------------------------------------
-------------
- `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
------------------------
- `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
------
- `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/>`__
-------------------------------------------------------------------------------
- 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