#########################################################################
Release Relevance
- 10.0.0 (Jakarta) - 6.0.0 (Frankfurt)
+ 11.x.x (Kohn) - 10.x.x (Jakarta)
Last Review/Update
- 14/03/2022
+ 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
-------------------------------------------------------------------------------
| GitLens | eamodio.gitlens | latest |
+--------------------------------------+---------------------------------------+---------+
-.. note:: Use the reStructuredText extension version 169.0.0 or lower to
+.. 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.
+ 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
------------------------
- 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?