summaryrefslogtreecommitdiffstats
path: root/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
diff options
context:
space:
mode:
authorthmsdt <thomas.kulik@telekom.de>2022-10-24 13:16:27 +0200
committerthmsdt <thomas.kulik@telekom.de>2022-10-24 14:38:26 +0200
commitaeadb240bf26195cdde389440dcd56f9a3245489 (patch)
treec4f14035062aea8c8da864b35a118ad1d27ae561 /docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
parent92906994d4eab62ac3521a84571e5a5b658e76e6 (diff)
fix doc guide
Issue-ID: DOC-798 Signed-off-by: thmsdt <thomas.kulik@telekom.de> Change-Id: I5b71a5ee7c92fbd0f88501236182a3e5d391b56f
Diffstat (limited to 'docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst')
-rw-r--r--docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst204
1 files changed, 77 insertions, 127 deletions
diff --git a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
index 0e3abf2ce..cf58cefc9 100644
--- a/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
+++ b/docs/guides/onap-documentation/setup-of-a-doc-dev-system.rst
@@ -42,7 +42,7 @@ Release Relevance
11.x.x (Kohn)
Last Review/Update
- 2022/10/20
+ 2022/10/24
Initial Release
2021/12/05
@@ -52,12 +52,6 @@ Author (Company)
-------------------------------------------------------------------------------
-.. warning:: There are known issues with the build and preview function in
- Vscode. This guide gets updated when a solution of the problem is
- available. Please excuse any inconvenience.
-
--------------------------------------------------------------------------------
-
.. contents:: Table of Contents
-------------------------------------------------------------------------------
@@ -157,7 +151,7 @@ Maybe you need to force a snap-store update with the following commands:
sudo snap refresh
Open :guilabel:`Ubuntu Software` again and check the :guilabel:`Updates` tab
-for required actions.
+for required actions.
Screen Lock
-----------
@@ -223,11 +217,8 @@ and add ``<USER> ALL=(ALL) NOPASSWD:ALL`` to the end of the file. Replace
Install python3 related packages
================================
-..
- .. important:: The main python3 package is preinstalled in Ubuntu. But please
- ensure that python version 3.8 is also available on your system.
-.. important:: The main python3 package is preinstalled in Ubuntu
+.. important:: The main python3 package comes preinstalled with Ubuntu
Open a :guilabel:`Terminal` window and update the package management system
with ...
@@ -256,18 +247,6 @@ Check the python3 version with ...
python3 -V
-..
- Install additional python version 3.8 and utils with ...
-
- .. code-block:: bash
-
- sudo apt install software-properties-common -y
- sudo add-apt-repository ppa:deadsnakes/ppa -y
- sudo apt update
- sudo apt install -y python3.8
- sudo apt install -y python3.8-distutils
-
-
-------------------------------------------------------------------------------
Install git and documentation related packages
@@ -359,40 +338,20 @@ Replace ``<GIT-EMAIL>`` and ``<GIT-USER>`` with your account details.
-------------------------------------------------------------------------------
-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``.
-
-.. important:: Currently an environment with python version 3.8 is required to
- build docs properly.
-
-..
- .. code-block:: bash
-
- cd ~
- mkdir environments
- cd ~/environments
- virtualenv -p /usr/bin/python3.8 onapdocs
- cd ~/environments/onapdocs
- source bin/activate
+Create working directory
+========================
+Create the working directory ``onapdocs`` in your home directory together with
+a ``repos`` directory to store various projects and versions. The full path is
+consequently ``~/onapdocs/repos``.
.. code-block:: bash
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)``.
+ mkdir onapdocs
+ cd onapdocs
+ mkdir repos
+ cd repos
-------------------------------------------------------------------------------
@@ -407,7 +366,7 @@ Linux Foundation (LF) account with ...
.. code-block:: bash
- cd ~/environments/onapdocs
+ cd ~/onapdocs/repos
git clone --branch master https://git.onap.org/doc/ ./doc
-------------------------------------------------------------------------------
@@ -420,40 +379,24 @@ Clone repo
.. code-block:: bash
- cd ~/environments/onapdocs
+ cd ~/onapdocs/repos
git clone ssh://<GIT-USER>@gerrit.onap.org:29418/doc
-------------------------------------------------------------------------------
-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
- 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)``.
-
-.. important:: Now you are installing packages only for the 'onapdocs' virtual
- environment.
+Install required Sphinx packages
+================================
-..
- .. code-block:: bash
+.. important:: By using ``sudo pip ...`` you will see a message saying:
+ "*WARNING: Running pip as the 'root' user can result in broken permissions
+ and conflicting behaviour with the system package manager*". We try to avoid
+ this installation method in a later version of this guide.
- pip install wheel \
- sphinxcontrib-spelling \
- pyenchant
-
+Install required Sphinx packages with ...
.. code-block:: bash
- pip install wheel
-
+ sudo pip install wheel
Continue with the installation of required packages. Use the file
``requirements-docs.txt`` for it. The file resides in the downloaded ``doc``
@@ -461,14 +404,14 @@ repository.
.. code-block:: bash
- pip install -r doc/etc/requirements-docs.txt
+ sudo pip install -r doc/etc/requirements-docs.txt
-------------------------------------------------------------------------------
Start VSC in the correct directory
==================================
-Start VSC (always) in the ``docs`` directory of your repository. For the
+Start VSC (always) in the ``docs`` directory of your repository. For the cloned
``doc`` repository used in this example do this with ...
.. code-block:: bash
@@ -478,7 +421,7 @@ Start VSC (always) in the ``docs`` directory of your repository. For the
.. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
-.. tip:: ``~/environments/onapdocs/doc/docs`` is now your
+.. tip:: ``~/onapdocs/repos/doc/docs`` is now your
``${workspaceFolder}`` because you have started VSC (``code .``) from here!
-------------------------------------------------------------------------------
@@ -517,24 +460,39 @@ extension in the :guilabel:`Search Extensions in Marketplace` window.
Press :guilabel:`Install` if you have found the required extension.
.. important:: You will experience, that VSC asks you to install additional
- components (e.g. the Esbonio Language Server, Trond Snekvik
- reStructuredText Syntax Highlighting). It is important to allow VSC the
- installation!
-
-
-Please install ...
+ components (e.g. Esbonio Language Server, reStructuredText Syntax
+ Highlighting). It is important to allow VSC the installation!
+
+
+Please manually install ...
+
++---------------------------------------+--------------------+------------+
+| IDENTIFIER (search) | NAME | TESTED |
++=======================================+====================+============+
+| ms-python.python | Python | v2022.16.1 |
++---------------------------------------+--------------------+------------+
+| lextudio.restructuredtext | reStructuredText | v189.1.0 |
++---------------------------------------+--------------------+------------+
+| eamodio.gitlens | GitLens | v13.0.3 |
++---------------------------------------+--------------------+------------+
+| streetsidesoftware.code-spell-checker | Code Spell Checker | v2.10.1 |
++---------------------------------------+--------------------+------------+
+| esbenp.prettier-vscode | Prettier | v9.9.0 |
++---------------------------------------+--------------------+------------+
+
+Together with the above extensions, the following software is automatically
+installed ...
+
++----------------------------+--------------------------------------+-------------+
+| IDENTIFIER (search) | NAME | TESTED |
++============================+======================================+=============+
+| ms-python.vscode-pylance | Pylance | v2022.10.30 |
++----------------------------+--------------------------------------+-------------+
+| several Jupyter Extensions | Jupyter ... | ... |
++----------------------------+--------------------------------------+-------------+
+| snekvik.simple-rst | reStructuredText Syntax highlighting | v1.5.2 |
++----------------------------+--------------------------------------+-------------+
-+---------------------------------------+--------------------------------------+-------------+
-| IDENTIFIER (search) | NAME | TESTED |
-+=======================================+======================================+=============+
-| ms-python.python | Python | v2022.14.0 |
-+---------------------------------------+--------------------------------------+-------------+
-| lextudio.restructuredtext | reStructuredText | v189.1.0 |
-+---------------------------------------+--------------------------------------+-------------+
-| eamodio.gitlens | GitLens | v12.2.1 |
-+---------------------------------------+--------------------------------------+-------------+
-| streetsidesoftware.code-spell-checker | Code Spell Checker | v2.7.2 |
-+---------------------------------------+--------------------------------------+-------------+
Close VSC and restart it using the ``code .`` command.
@@ -555,8 +513,6 @@ Values for the following parameters need to be changed:
- Restructuredtext › Linter › Rst-lint: Executable Path
- Restructuredtext › Linter › Rstcheck: Executable Path
- Esbonio › Sphinx: Build Dir
-- Esbonio › Sphinx: Conf Dir
-- Esbonio › Sphinx: Src Dir
- Restructuredtext: Styles
@@ -584,13 +540,9 @@ the listed values:
* - restructuredtext.linter.rstcheck.executablePath
- /usr/bin/doc8
* - esbonio.sphinx.buildDir
- - ${workspaceFolder}/_build/html
- * - esbonio.sphinx.confDir
- - ${workspaceFolder}
- * - esbonio.sphinx.srcDir
- - ${workspaceFolder}
+ - ${workspaceFolder}/_build
* - restructuredtext.styles
- - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css
+ - "/usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css"
Close the :guilabel:`Extension Settings` window.
@@ -606,9 +558,7 @@ should now include the following entries:
"restructuredtext.linter.doc8.executablePath": "/usr/bin/doc8",
"restructuredtext.linter.rst-lint.executablePath": "/usr/bin/doc8",
"restructuredtext.linter.rstcheck.executablePath": "/usr/bin/doc8",
- "esbonio.sphinx.buildDir": "${workspaceFolder}/_build/html",
- "esbonio.sphinx.confDir": "${workspaceFolder}",
- "esbonio.sphinx.srcDir": "${workspaceFolder}",
+ "esbonio.sphinx.buildDir": "${workspaceFolder}/_build",
"restructuredtext.styles": [
"/usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css"
]
@@ -655,11 +605,11 @@ Build documentation locally
---------------------------
To build documentation locally use the ``tox`` command, check the output for
-error messages and check the files using your favorite browser.
+error messages and check the files using your favorite browser.
.. code-block:: bash
- cd ~/environments/onapdocs/doc
+ cd ~/onapdocs/repos/doc
tox
... (checks are executed, docs are build, check logging output) ...
cd docs/_build/html
@@ -865,21 +815,21 @@ Backlog
There are still some open topics or issues in this guide. They are subject
for one of the upcoming releases.
- - fix issues with virtual environments using different python versions
- - consider ``pandoc`` in this guide?
- - keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
- :kbd:`X` Is this a problem in the RTD theme?
- - use ``menuselection``
- :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
- - evaluate and add VSC extension to "draw" tables in an aided way
- - add infos for config files, e.g. ``conf.py``, ``conf.yaml``
- - find the reason for VSC error message
- ``Substitution definition "ShowApp" empty or invalid.``
- - find the reason for VSC error message
- ``Unexpected indentation``
- - find a solution to wrap lines in VSC automatically (79 chars limit)
- - add a table explaining the role of installed packages/extensions in every
- section
+- fix issues with virtual environments using different python versions in VCS
+- consider ``pandoc`` in this guide?
+- keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
+ :kbd:`X` Is this a problem in the RTD theme?
+- use ``menuselection``
+ :menuselection:`My --> Software --> Some menu --> Some sub menu 1`?
+- evaluate and add VSC extension to "draw" tables in an aided way
+- add infos for config files, e.g. ``conf.py``, ``conf.yaml``
+- find the reason for VSC error message
+ ``Substitution definition "ShowApp" empty or invalid.``
+- find the reason for VSC error message
+ ``Unexpected indentation``
+- find a solution to wrap lines in VSC automatically (79 chars limit)
+- add a table explaining the role of installed packages/extensions in every
+ section
..
#########################################################################