[LTP] [PATCH v1] doc: Documentation usage and development

Andrea Cervesato
2024-04-12T10:08:01Z

From: Andrea Cervesato <andrea.cervesato@suse.com>

This patch adds a section for developers, explaining how to use and
build the new LTP documentation.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
doc/developers/documentation.rst | 49 ++++++++++++++++++++++++++++++++
doc/index.rst | 4 +++
2 files changed, 53 insertions(+)
create mode 100644 doc/developers/documentation.rst

diff --git a/doc/developers/documentation.rst b/doc/developers/documentation.rst
new file mode 100644
index 000000000..5b112bcaf
--- /dev/null
+++ b/doc/developers/documentation.rst
@@ -0,0 +1,49 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Documentation
+=============
+
+This section explains how to use and develop the LTP documentation. The current
+documentation format is written using
+`reStructedText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+and it's built on top of `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+
+Building documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+First of all, to build the documentation we must be sure that all dependences
+have been installed (please check ``doc/requirements.txt`` file). Sometimes the
+Linux distros are providing them, but the best way is to use ``virtualenv``
+command as following:
+
+.. code-block:: bash
+
+ cd doc
+
+ # prepare virtual enviroment
+ python -m virtualenv .venv
+ source .venv/bin/activate
+
+ pip install sphinx
+ pip install -r requirements.txt
+
+ # build documentation
+ make
+
+Once the procedure has been completed, documentation will be visible at
+``doc/html/index.html``.
+
+.. warning::
+
+ The current ``.readthedocs.yml`` workflow is using ``Python 3.6`` because
+ other Python versions were causing issues. No other version has been tested,
+ but it should work anyway.
+
+Validating spelling
+~~~~~~~~~~~~~~~~~~~
+
+To check documentation words spelling, we provide support for
+`aspell <http://aspell.net/>`_, so make sure that it's installed. The
+documentation can be tested via ``make spelling`` command. Output will be
+visible in the ``doc/build`` folder and, if any error will be found, a warning
+message will be shown.
diff --git a/doc/index.rst b/doc/index.rst
index 80820ab51..653449cc4 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -27,6 +27,7 @@
developers/ltp_library
developers/build_system
developers/debugging
+ developers/documentation

.. toctree::
:maxdepth: 3
@@ -88,6 +89,9 @@ For developers
:doc:`developers/debugging`
How to debug LTP tests

+:doc:`developers/documentation`
+ How to use and develop LTP documentation
+
For maintainers
---------------

--
2.35.3

--
Mailing list info: https://lists.linux.it/listinfo/ltp