From 03402c81241a80c2ddb27c963a4031bfbc46ed59 Mon Sep 17 00:00:00 2001 From: thmsdt Date: Thu, 13 Oct 2022 16:37:42 +0200 Subject: [PATCH] update doc guide to include py3.8 support Issue-ID: DOC-798 Signed-off-by: thmsdt Change-Id: I0c055c2a27b5f53c6e539e55f2d4ed58d1aa637b --- .../setup-of-a-doc-dev-system.rst | 161 +++++++++++++++------ examples/sphinx/.readthedocs.yaml | 2 +- 2 files changed, 119 insertions(+), 44 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 f02851abf..49615f46e 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 @@ -39,10 +39,10 @@ Setup of a Documentation Development System ######################################################################### Release Relevance - 11.x.x (Kohn) - 10.x.x (Jakarta) + 11.x.x (Kohn) Last Review/Update - 2022/09/06 + 2022/10/18 Initial Release 2021/12/05 @@ -52,6 +52,12 @@ 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 ------------------------------------------------------------------------------- @@ -143,6 +149,16 @@ Software Updates Open :guilabel:`Software Updater` and update installed Ubuntu packages. You may need to restart the system afterwards. +Maybe you need to force a snap-store update with the following commands: + +.. code-block:: bash + + snap-store --quit + sudo snap refresh + +Open :guilabel:`Ubuntu Software` again and check the :guilabel:`Updates` tab +for required actions. + Screen Lock ----------- @@ -207,9 +223,11 @@ and add `` 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. But please - ensure that you are using python version 3.8 or higher. +.. important:: The main python3 package is preinstalled in Ubuntu Open a :guilabel:`Terminal` window and update the package management system with ... @@ -229,7 +247,7 @@ Install python3 related packages with ... libssl-dev \ libffi-dev \ python3-dev \ - python3-venv + python3-virtualenv Check the python3 version with ... @@ -238,6 +256,18 @@ 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 @@ -253,8 +283,9 @@ Install the required packages with ... python3-doc8 \ docutils \ curl \ - jq \ - tox + tox \ + jq + Check git version and the path of the sphinx-build executable with ... @@ -334,7 +365,21 @@ 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``. +``~/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 + .. code-block:: bash @@ -345,6 +390,7 @@ the virtual environment ``onapdocs`` is created. The full path is consequently 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)``. @@ -396,9 +442,18 @@ your terminal has changed. Now it starts with ``(onapdocs)``. .. important:: Now you are installing packages only for the 'onapdocs' virtual environment. +.. + .. code-block:: bash + + pip3 install wheel \ + sphinxcontrib-spelling \ + pyenchant + + .. code-block:: bash - pip3 install wheel + sudo 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`` @@ -406,8 +461,7 @@ repository. .. code-block:: bash - cd ~/environments/onapdocs - sudo pip install -r doc/etc/requirements-docs.txt + sudo pip3 install -r doc/etc/requirements-docs.txt ------------------------------------------------------------------------------- @@ -462,6 +516,12 @@ or use the keyboard shortcut ``[Ctrl+Shift+X]``. Then enter the name of the 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 ... +---------------------------------------+--------------------------------------+-------------+ @@ -471,8 +531,6 @@ Please install ... +---------------------------------------+--------------------------------------+-------------+ | lextudio.restructuredtext | reStructuredText | v189.1.0 | +---------------------------------------+--------------------------------------+-------------+ -| trond-snekvik.simple-rst | reStructuredText Syntax highlighting | v1.5.2 | -+---------------------------------------+--------------------------------------+-------------+ | eamodio.gitlens | GitLens | v12.2.1 | +---------------------------------------+--------------------------------------+-------------+ | streetsidesoftware.code-spell-checker | Code Spell Checker | v2.7.2 | @@ -480,9 +538,6 @@ Please install ... Close VSC and restart it using the ``code .`` command. -You may experience, that VSC asks you to install additional components -(e.g. the Esbonio Language Server). Please allow VSC to install them. - Configure reStructuredText extension ------------------------------------ @@ -496,19 +551,23 @@ all the parameters. We need to change values for ... -``Restructuredtext › Linter › Doc8: Executable Path`` - -``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`` +.. list-table:: + :header-rows: 0 + + * - Restructuredtext › Linter › Doc8: Executable Path + - Points to doc8 executable + * - Restructuredtext › Linter › Rst-lint: Executable Path + - Points to doc8 executable + * - Restructuredtext › Linter › Rstcheck: Executable Path + - Points to doc8 executable + * - Esbonio › Sphinx: Build Dir + - Directory to store Sphinx's build output + * - Esbonio › Sphinx: Conf Dir + - Directory containing 'conf.py' file + * - Esbonio › Sphinx: Src Dir + - Directory containing rst source files + * - Restructuredtext: Styles + - Paths to CSS style sheets for preview .. important:: Ensure that you are changing parameters in :guilabel:`User` @@ -534,15 +593,14 @@ the listed values: - /usr/bin/doc8 * - restructuredtext.linter.rstcheck.executablePath - /usr/bin/doc8 - * - restructuredtext.styles - - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css * - esbonio.sphinx.buildDir - ${workspaceFolder}/_build/html * - esbonio.sphinx.confDir - ${workspaceFolder} * - esbonio.sphinx.srcDir - ${workspaceFolder} - + * - restructuredtext.styles + - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css Close the :guilabel:`Extension Settings` window. @@ -553,17 +611,18 @@ should now include the following entries: .. code-block:: bash - "telemetry.telemetryLevel": "off", - "restructuredtext.linter.doc8.executablePath": "/usr/bin/doc8", - "restructuredtext.linter.rst-lint.executablePath": "/usr/bin/doc8", - "restructuredtext.linter.rstcheck.executablePath": "/usr/bin/doc8", - "restructuredtext.styles": [ - /usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css - ] - "esbonio.sphinx.buildDir": "${workspaceFolder}/_build/html", - "esbonio.sphinx.confDir": "${workspaceFolder}", - "esbonio.sphinx.srcDir": "${workspaceFolder}" - + { + "telemetry.telemetryLevel": "off", + "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}", + "restructuredtext.styles": [ + "/usr/local/lib/python3.10/dist-packages/sphinx_rtd_theme/static/css/theme.css" + ] + } ------------------------------------------------------------------------------- @@ -602,6 +661,21 @@ right) or use keyboard shortcut ``[Ctrl+k Ctrl+r]`` to open the preview window on the right hand side. This may take a few seconds. The preview shows up and renders the ``index.rst`` as it would look like on ReadTheDocs. +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. + +.. code-block:: bash + + cd ~/environments/onapdocs/doc + tox + ... (checks are executed, docs are build, check logging output) ... + cd docs/_build/html + firefox ./index.html + + Tips and Tricks --------------- @@ -795,6 +869,7 @@ 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? diff --git a/examples/sphinx/.readthedocs.yaml b/examples/sphinx/.readthedocs.yaml index 49997a761..7f740b769 100644 --- a/examples/sphinx/.readthedocs.yaml +++ b/examples/sphinx/.readthedocs.yaml @@ -12,7 +12,7 @@ build: python: version: 3.7 install: - - requirements: requirements-docs.txt + - requirements: docs/requirements-docs.txt submodules: include: all -- 2.16.6