Skip to content

Commit

Permalink
update doc dev guide
Browse files Browse the repository at this point in the history 
Issue-ID: DOC-798

Signed-off-by: thmsdt <[email protected]>
Change-Id: Ie64489dded1811d86fff5a19e0c880053af764e2
  • Loading branch information
@thmsdt
thmsdt committed Sep 6, 2022
1 parent 624b784 commit 555bc1f
Showing 1 changed file with 102 additions and 70 deletions.
172 changes: 102 additions & 70 deletions docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Release Relevance
11.x.x (Kohn) - 10.x.x (Jakarta)

Last Review/Update
2022/09/01
2022/09/06

Initial Release
2021/12/05
Expand Down Expand Up @@ -78,6 +78,12 @@ 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.

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
Expand Down Expand Up @@ -197,7 +203,8 @@ and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
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 ...
Expand Down Expand Up @@ -243,7 +250,7 @@ Install the required packages 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
Expand All @@ -258,64 +265,87 @@ Check the git version and the path of the sphinx-build executable ...

-------------------------------------------------------------------------------

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)``.

-------------------------------------------------------------------------------

Expand All @@ -338,42 +368,36 @@ Linux Foundation (LF) account with ...
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``
Expand Down Expand Up @@ -640,11 +664,18 @@ Gerrit

- `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
--------------------------------------------
Expand All @@ -665,12 +696,13 @@ ReadTheDocs
-----------

- `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
Expand Down

0 comments on commit 555bc1f

Please sign in to comment.