1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3Documentation 4============= 5 6This section explains how to use and develop the LTP documentation. The current 7documentation format is written using 8`reStructedText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ 9and it's built on top of `Sphinx <https://www.sphinx-doc.org/en/master/>`_. 10 11Building documentation 12~~~~~~~~~~~~~~~~~~~~~~ 13 14First of all, to build the documentation we must be sure that all dependencies 15have been installed (please check :master:`doc/requirements.txt` file). Sometimes the 16Linux distros are providing them, but the best way is to use ``virtualenv`` 17command as following: 18 19.. code-block:: bash 20 21 cd doc 22 23 # prepare virtual enviroment 24 python3 -m virtualenv .venv 25 . .venv/bin/activate 26 27 pip install sphinx # usually packaged in distros 28 pip install -r requirements.txt 29 30 # build documentation 31 make 32 33Once the procedure has been completed, documentation will be visible at 34``doc/html/index.html``. 35 36.. warning:: 37 38 The current :master:`.readthedocs.yml` workflow is using ``Python 3.6`` because 39 older Python versions were causing issues. No other version has been tested, 40 but it should work anyway. 41 42Validating spelling 43~~~~~~~~~~~~~~~~~~~ 44 45To check documentation words spelling, we provide support for 46`aspell <http://aspell.net/>`_, so make sure that it's installed. The 47documentation can be tested via ``make spelling`` command. Output will be 48visible in the ``doc/build`` folder and, if any error will be found, a warning 49message will be shown. 50 51C API documentation 52~~~~~~~~~~~~~~~~~~~ 53 54The C API documentation is generated from headers using 55`kernel-doc <https://return42.github.io/linuxdoc/linuxdoc-howto/kernel-doc-syntax.html>`_ 56syntax which is supported by Sphinx via 57`linuxdoc <https://pypi.org/project/linuxdoc/>`_ extension. 58