Introduce Doxygen support inside documentation

With Doxygen support inside documentation, we are able to generate
a full API documentation from LTP headers. The idea is that we don't
need to keep track of both source code and API documentation files,
but we will auto-generate any API documentation via Doxygen + Sphinx.

.readthedocs.yml

@@ -4,6 +4,9 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.6"
+  jobs:
+    pre_build:
+      - cd doc_new && doxygen Doxygen.in
 
 # Build from the docs/ directory with Sphinx
 sphinx:

doc_new/Doxygen.in

@@ -0,0 +1,7 @@
+GENERATE_XML = YES
+GENERATE_LATEX = NO
+GENERATE_HTML = NO
+HIDE_IN_BODY_DOCS = YES
+EXTRACT_ALL = YES
+INPUT = ../include
+OUTPUT_DIRECTORY = .

doc_new/conf.py

@@ -3,6 +3,9 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import os
+import subprocess
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -14,7 +17,9 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+# Doxygen support
+extensions = ['breathe']
+breathe_default_project = "ltp"
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -25,3 +30,8 @@
 
 def setup(app):
     app.add_css_file('custom.css')
+
+# generate API documentation via Doxygen if we are not
+# inside a readthedocs container
+if not os.environ.get('READTHEDOCS', None):
+    subprocess.call('doxygen Doxygen.in', shell=True)

doc_new/developers/api_c_tests.rst

@@ -1,4 +1,11 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. Generate API documentation with:
+..  doxygen Doxygen.in
+..  sphinx-build -b html -Dbreathe_projects.ltp=xml . html
+
+.. Include them in this file with:
+.. .. doxygenfile:: tst_uid.h
+
 Developing using C API
 ======================

doc_new/developers/api_kvm_tests.rst

@@ -1,4 +1,11 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. Generate API documentation with:
+..  doxygen Doxygen.in
+..  sphinx-build -b html -Dbreathe_projects.ltp=xml . html
+
+.. Include them in this file with:
+.. .. doxygenfile:: tst_uid.h
+
 Developing using KVM API
 ========================

doc_new/developers/api_network_tests.rst

@@ -1,4 +1,11 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. Generate API documentation with:
+..  doxygen Doxygen.in
+..  sphinx-build -b html -Dbreathe_projects.ltp=xml . html
+
+.. Include them in this file with:
+.. .. doxygenfile:: tst_uid.h
+
 Developing using network API
 ============================

doc_new/requirements.txt

@@ -1 +1,2 @@
 sphinx-rtd-theme==2.0.0
+breathe==4.35.0