diff mbox series

[v1] doc: Documentation usage and development

Message ID 20240412100739.1169-1-andrea.cervesato@suse.de
State Accepted
Headers show
Series [v1] doc: Documentation usage and development | expand

Commit Message

Andrea Cervesato April 12, 2024, 10:07 a.m. UTC 
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

Comments

Cyril Hrubis April 12, 2024, 2:22 p.m. UTC | #1 
Hi!
Applied, thanks.
diff mbox series

Patch

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
 ---------------