* [LTP] [PATCH v1] doc: Documentation usage and development
@ 2024-04-12 10:07 Andrea Cervesato
2024-04-12 14:22 ` Cyril Hrubis
0 siblings, 1 reply; 2+ messages in thread
From: Andrea Cervesato @ 2024-04-12 10:07 UTC (permalink / raw)
To: ltp
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
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [LTP] [PATCH v1] doc: Documentation usage and development
2024-04-12 10:07 [LTP] [PATCH v1] doc: Documentation usage and development Andrea Cervesato
@ 2024-04-12 14:22 ` Cyril Hrubis
0 siblings, 0 replies; 2+ messages in thread
From: Cyril Hrubis @ 2024-04-12 14:22 UTC (permalink / raw)
To: Andrea Cervesato; +Cc: ltp
Hi!
Applied, thanks.
--
Cyril Hrubis
chrubis@suse.cz
--
Mailing list info: https://lists.linux.it/listinfo/ltp
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2024-04-12 14:24 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-04-12 10:07 [LTP] [PATCH v1] doc: Documentation usage and development Andrea Cervesato
2024-04-12 14:22 ` Cyril Hrubis
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).