11.x.x (Kohn) - 10.x.x (Jakarta)
Last Review/Update
- 2022/09/01
+ 2022/09/06
Initial Release
2021/12/05
changed and the support of submodules was removed. Although large parts of this
guide are valid for earlier releases, the relevance has been limited.
+If you plan to contribute to the ONAP community and you want to submit changes
+to a specific project later on, please refer to the
+`Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
+and the `ONAP Developer Wiki <https://wiki.onap.org>`__ to get information
+about all the prerequisite details.
+
-------------------------------------------------------------------------------
VM Configuration
Install python3 related packages
================================
-.. note:: The main python3 package is preinstalled in Ubuntu 20.04.
+.. important:: The main python3 package is preinstalled in Ubuntu 20.04. But
+ please ensure that you are using python version 3.8 or higher.
Open a :guilabel:`Terminal` window and update the package management system
with ...
jq \
tox
-Check the git version and the path of the sphinx-build executable ...
+Check git version and the path of the sphinx-build executable with ...
.. code-block:: bash
-------------------------------------------------------------------------------
-Create virtual environment and activate
-=======================================
-
-In this guide, virtual environments are generally located in your home
-directory under ``~/environments``. For the development of ONAP documentation
-the virtual environment ``onapdocs`` is created. The full path is consequently
-``~/environments/onapdocs``.
+Install Visual Studio Code (VSC) and update applications
+========================================================
-.. code-block:: bash
+The following actions are performed on the Ubuntu desktop. You may use the
+desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
+the bottom left corner) to find the required applications.
- cd ~
- mkdir environments
- cd ~/environments
- python3 -m venv onapdocs
- cd ~/environments/onapdocs
- source bin/activate
+Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
+:guilabel:`vscode` (Visual Studio Code) and press :guilabel:`Install` to
+install the integrated development environment (IDE).
-To indicate that you are now working in an virtual environment, the prompt of
-your terminal has changed. Now it starts with ``(onapdocs)``.
+Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
+installed applications are up to date.
-------------------------------------------------------------------------------
-Install required Sphinx packages in activated environment (I)
-=============================================================
+Configure ssh
+=============
-It is :strong:`important` to activate the ``onapdocs`` environment before you
-continue. If not already done, activate environment with ...
+If you already have a LF account and you have shared your public ssh key you
+can finalize the configuration of this development system by updating your ssh
+configuration in the ``~/.ssh`` directory by copying over ``config``,
+``id_{algorithm}`` and ``id_{algorithm}.pub``
-.. code-block:: bash
+.. warning:: If your ssh key has been generated using the RSA SHA-1 hash
+ algorithm, you may experience problems when connecting to other systems.
- cd ~/environments/onapdocs
- source bin/activate
+ The RSA SHA-1 hash algorithm has been quickly deprecated across operating
+ systems and SSH clients because of various security vulnerabilities,
+ with many of these technologies now outright denying the use of this
+ algorithm. You need to create new ssh keys using a more secure algorithm.
-To indicate that you are now working in an virtual environment, the prompt of
-your terminal has changed. Now it starts with ``(onapdocs)``.
+ You may try to temporarily enable the insecure RSA SHA-1 hash algorithm by
+ adding the line ``PubkeyAcceptedKeyTypes +ssh-rsa`` to your ssh ``config``
+ file.
-.. important:: Now you are installing packages only for the 'onapdocs' virtual
- environment.
+.. tip:: Please refer to the
+ `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
+ for additional information.
+
+-------------------------------------------------------------------------------
+
+Configure git
+=============
+
+Configure ``git`` and ``git-review`` with ...
.. code-block:: bash
- pip3 install wheel
+ git config --global user.email "<GIT-EMAIL>"
+ git config --global user.name "<GIT-USER>"
+ git config --global --add gitreview.username "<GIT-USER>"
+ git config --global gitreview.remote origin
+
+Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
+
+.. tip:: Please refer to the
+ `Linux Foundation Release Engineering Documentation <https://docs.releng.linuxfoundation.org/>`__
+ for additional information.
-------------------------------------------------------------------------------
-Install Visual Studio Code (VSC) and update already installed applications
-==========================================================================
+Create virtual environment and activate
+=======================================
-The following actions are performed on the Ubuntu desktop. You may use the
-desktop search function :guilabel:`Show Applications` (the |ShowApp| symbol in
-the bottom left corner) to find the required applications.
+In this guide, virtual environments are generally located in your home
+directory under ``~/environments``. For the development of ONAP documentation
+the virtual environment ``onapdocs`` is created. The full path is consequently
+``~/environments/onapdocs``.
-Open :guilabel:`Ubuntu Software` > :guilabel:`Development`, select
-:guilabel:`code` (Visual Studio Code) and press :guilabel:`Install` to install
-the integrated development environment (IDE).
+.. code-block:: bash
-Open :guilabel:`Ubuntu Software` > :guilabel:`Updates` to ensure that your
-installed applications are up to date.
+ cd ~
+ mkdir environments
+ cd ~/environments
+ python3 -m venv onapdocs
+ cd ~/environments/onapdocs
+ source bin/activate
+
+To indicate that you are now working in an virtual environment, the prompt of
+your terminal has changed. Now it starts with ``(onapdocs)``.
-------------------------------------------------------------------------------
Clone example repo (LF account used)
====================================
-Prerequisite configuration
---------------------------
-
-If you plan to contribute to the ONAP community and you want to submit changes
-to a specific project later on, please refer to the
-`ONAP Developer Wiki <https://wiki.onap.org>`__ to get information about all
-the prerequisite details.
-
-If you already have a LF account and you have shared your public ssh key you
-can finalize the configuration of this development system by updating your ssh
-configuration in the ``~/.ssh`` directory by copying over ``config``,
-``id_rsa`` and ``id_rsa.pub``
-
-In addition you configure ``git`` and ``git-review`` with ...
+Clone repo
+----------
.. code-block:: bash
- git config --global user.email "<GIT-EMAIL>"
- git config --global user.name "<GIT-USER>"
- git config --global --add gitreview.username "<GIT-USER>"
- git config --global gitreview.remote origin
+ cd ~/environments/onapdocs
+ git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
-Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
+-------------------------------------------------------------------------------
-Clone repo
-----------
+Install required Sphinx packages in activated environment
+=========================================================
+
+It is :strong:`important` to work in the ``onapdocs`` virtual environment. If
+not already done, activate environment with ...
.. code-block:: bash
cd ~/environments/onapdocs
- git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
+ source bin/activate
--------------------------------------------------------------------------------
+To indicate that you are now working in an virtual environment, the prompt of
+your terminal has changed. Now it starts with ``(onapdocs)``.
-Install required Sphinx packages in activated environment (II)
-==============================================================
+.. important:: Now you are installing packages only for the 'onapdocs' virtual
+ environment.
+
+.. code-block:: bash
+
+ pip3 install wheel
Continue with the installation of required packages. Use the file
``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
- `LF RelEng Gerrit Guide <https://docs.releng.linuxfoundation.org/en/latest/gerrit.html>`_
-Git
----
+Git/GitHub
+----------
-- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
+- `GitHub Authentication <https://docs.github.com/en/authentication>`__
- `How To Install Git on Ubuntu 20.04 <https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-20-04>`__
+- `LF RelEng Git Guide <https://docs.releng.linuxfoundation.org/en/latest/git.html>`__
+
+Linux Foundation Release Engineering
+------------------------------------
+
+- `LF RelEng Documentation (recommended reading) <https://docs.releng.linuxfoundation.org>`__
+
ONAP Documentation Procedures for Developers
--------------------------------------------
-----------
- `Documentation <https://docs.readthedocs.io/en/stable/>`__
+- `Tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`__
- `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 (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
Code Review / doc.git / commitdiff