11.x.x (Kohn)
Last Review/Update
- 2022/10/20
+ 2022/10/24
Initial Release
2021/12/05
-------------------------------------------------------------------------------
-.. 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
-------------------------------------------------------------------------------
sudo snap refresh
Open :guilabel:`Ubuntu Software` again and check the :guilabel:`Updates` tab
-for required actions.
+for required actions.
Screen Lock
-----------
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 ...
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
-------------------------------------------------------------------------------
-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
-------------------------------------------------------------------------------
.. code-block:: bash
- cd ~/environments/onapdocs
+ cd ~/onapdocs/repos
git clone --branch master https://git.onap.org/doc/ ./doc
-------------------------------------------------------------------------------
.. 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``
.. 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
.. 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!
-------------------------------------------------------------------------------
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.
- 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
* - 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.
"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"
]
---------------------------
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
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
..
#########################################################################
Code Review / doc.git / commitdiff