------------
+--------------------------------------+
-| ubuntu-20.04.3-desktop-amd64.iso |
+| ubuntu-22.04.1-desktop-amd64.iso |
+--------------------------------------+
Please check what image must be used for your type of hardware.
Software Updates
----------------
-Open :guilabel:`Software Updater` and update already installed Ubuntu packages.
+Open :guilabel:`Software Updater` and update installed Ubuntu packages.
You may need to restart the system afterwards.
+Screen Lock
+-----------
+
+Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
+:guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
+and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
+window.
+
+-------------------------------------------------------------------------------
+
+An older version of Ubuntu LTS (e.g. 20.4.) may need additional configuration
+steps for proper localization:
+
Language Support
----------------
of the list using drag and drop. Close the window. You may need to logout from
the UI and login again to make your changes effective.
-Screen Lock
------------
-
-Open :guilabel:`Settings`. Navigate to :guilabel:`Privacy` >
-:guilabel:`Screen Lock` and change settings for :guilabel:`Blank Screen Delay`
-and :guilabel:`Automatic Screen Lock` to values of your choice. Close the
-window.
-
-------------------------------------------------------------------------------
Disable sudo password for your user
Install python3 related packages
================================
-.. important:: The main python3 package is preinstalled in Ubuntu 20.04. But
- please ensure that you are using python version 3.8 or higher.
+.. important:: The main python3 package is preinstalled in Ubuntu. 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 ...
git-review \
python3-sphinx \
python3-doc8 \
+ docutils \
curl \
jq \
tox
which sphinx-build
-
-.. tip:: Remember the path
- ``/usr/bin/sphinx-build``, you need it later
- to configure a VSC extension.
-
-------------------------------------------------------------------------------
Install Visual Studio Code (VSC) and update applications
.. code-block:: bash
- cd doc
- cd docs
+ cd doc/docs
code .
.. important:: Don't forget the ``.`` (dot) when you start Visual Studio Code.
-------------------------------------------------------------------------------
-Install VSC extensions and configure reStructuredText extension
-===============================================================
+Install VSC extensions and configure them
+=========================================
Install VSC extensions
----------------------
Please install ...
-+--------------------------------------+---------------------------------------+---------+
-| Python | ms-python.python | latest |
-+--------------------------------------+---------------------------------------+---------+
-| reStructuredText | lextudio.restructuredtext | 169.0.0 |
-+--------------------------------------+---------------------------------------+---------+
-| reStructuredText Syntax highlighting | trond-snekvik.simple-rst | latest |
-+--------------------------------------+---------------------------------------+---------+
-| Code Spell Checker | streetsidesoftware.code-spell-checker | latest |
-+--------------------------------------+---------------------------------------+---------+
-| Prettier | esbenp.prettier-vscode | latest |
-+--------------------------------------+---------------------------------------+---------+
-| GitLens | eamodio.gitlens | latest |
-+--------------------------------------+---------------------------------------+---------+
-
-.. warning:: Use the reStructuredText extension version 169.0.0 or lower to
- avoid problems with the preview. You need to downgrade after the initial
- installation. This can be done by using
- :guilabel:`Uninstall` > :guilabel:`Install Another Version...` in the VSC
- extension management.
++---------------------------------------+--------------------------------------+-------------+
+| IDENTIFIER (search) | NAME | TESTED |
++=======================================+======================================+=============+
+| ms-python.python | Python | v2022.14.0 |
++---------------------------------------+--------------------------------------+-------------+
+| 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 |
++---------------------------------------+--------------------------------------+-------------+
+
+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
------------------------------------
:guilabel:`Search Extensions in Marketplace` window. After you have found the
extension press :guilabel:`Manage` (the little |GearSymb| symbol on the right
bottom) and select :guilabel:`Extension Settings`. A new windows in VSC shows
-all the parameters. Change the following ones:
+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``
- :strong:`Restructuredtext › Linter: Executable Path`
- ``/usr/bin/doc8``
+``Esbonio › Sphinx: Src Dir``
- :strong:`Restructuredtext › Linter: Name`
- ``doc8``
+``Restructuredtext: Styles``
- :strong:`Restructuredtext: Sphinx Build Path`
- ``/usr/bin/sphinx-build``
-Replace ``<USER>`` with your user name.
+.. important:: Ensure that you are changing parameters in :guilabel:`User`
+ Settings and :strong:`not` in :guilabel:`Workspace` Settings.
+ :guilabel:`User` Settings are applied globally - for every running instance
+ of VSC.
-Only in case the preview creates an error message, try ...
+.. tip:: If you experience problems adding the value to
+ ``restructuredtext.styles`` via editing the ``settings.json`` in VSC, please
+ use an external editor (e.g. ``vi``) to add the value.
+
+Search the following parameter in the :guilabel:`Search settings` field and add
+the listed values:
+
+.. list-table:: VSC User Settings for reStructuredText
+ :header-rows: 1
+
+ * - PARAMETER (search)
+ - VALUE
+ * - 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}
- :strong:`Restructuredtext: Conf Path`
- ``${workspaceFolder}/docs``
Close the :guilabel:`Extension Settings` window.
-Close VSC and start it again with the ``code .`` command.
+Close VSC and restart it using the ``code .`` command.
+
+Your VSC User Settings file ``/home/<USER>/.config/Code/User/settings.json``
+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}"
+
-------------------------------------------------------------------------------
:guilabel:`Problems` to open an additional window at the bottom of VSC.
When you select a specific entry in the problem list, the code window is
-updated to show the related line in the code.
+updated to show the related line in the code. To show only problems for the
+:strong:`active` file in VSC, set the filter to
+:guilabel:`Show Active File Only`.
Preview
-------
The content of ``conf.py`` affects how the documentation is presented.
- VSC may claim that some packages require an update. This can be easily
fixed. VSC offers automatically to install or update the package.
- - VSC may ask you to install ``snooty``. Please install.
- Select the correct environment in the (blue) bottom line
``'onapdocs':venv``. Have also a view on the other interesting
information (e.g. the ``conf.py`` which is currently in use).
for one of the upcoming releases.
- consider ``pandoc`` in this guide?
- - VSC / reStructuredText Extension Settings / reStructuredText: Sphinx Build
- Path: ${workspaceRoot} , ${workspaceFolder} , any alternatives?
- - VSC extension configuration: Difference between "Workspace" and "User"?
- - link to full ``ssh`` install/config?
- - link to full ``git`` install/config?
- - how to limit line width to improve readability? setting in conf.py?
- keyboard shortcut ``[Ctrl+Shift+X]`` or :kbd:`Ctrl` + :kbd:`Shift` +
:kbd:`X` Is this a problem in the RTD theme?
- use ``menuselection``
- find the reason for VSC error message
``Unexpected indentation``
- find a solution to wrap lines in VSC automatically (79 chars limit)
- - evaluate ``snooty`` and describe functionality (build in? not a extension?)
- add a table explaining the role of installed packages/extensions in every
section
- - update instructions to enable use of latest reStructuredText VSC extension
..
#########################################################################
Code Review / doc.git / commitdiff