From: Andrea Cervesato <andrea.cervesato@suse.de>
To: ltp@lists.linux.it
Subject: [LTP] [PATCH v1] doc: Documentation usage and development
Date: Fri, 12 Apr 2024 12:07:39 +0200 [thread overview]
Message-ID: <20240412100739.1169-1-andrea.cervesato@suse.de> (raw)
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
next reply other threads:[~2024-04-12 10:08 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-12 10:07 Andrea Cervesato [this message]
2024-04-12 14:22 ` [LTP] [PATCH v1] doc: Documentation usage and development Cyril Hrubis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240412100739.1169-1-andrea.cervesato@suse.de \
--to=andrea.cervesato@suse.de \
--cc=ltp@lists.linux.it \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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 read-only IMAP folder(s) and NNTP newsgroup(s).