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/.gitignore

@@ -1 +1,2 @@
+xml/
 html/

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

@@ -2,4 +2,4 @@ all:
 	sphinx-build -b html . html
 
 clean:
-	rm -rf html/
+	rm -rf xml/ html/

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,14 +17,25 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
-
+# Doxygen support
+extensions = ['breathe']
+breathe_default_project = "ltp"
+breathe_projects = {'ltp': 'xml'}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
+def generate_doxygen_xml(app):
+    """
+    Generate API documentation via Doxygen if we are not
+    inside a readthedocs server.
+    """
+    if not os.environ.get('READTHEDOCS', None):
+        subprocess.call('doxygen Doxygen.in', shell=True)
+
 def setup(app):
     app.add_css_file('custom.css')
+    app.connect("builder-inited", generate_doxygen_xml)

doc_new/developers/api_c_tests.rst

@@ -1,4 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. Include them in this file with:
+.. .. doxygenfile:: tst_uid.h
+
 Developing using C API
 ======================

doc_new/developers/api_kvm_tests.rst

@@ -1,4 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. Include them in this file with:
+.. .. doxygenfile:: tst_uid.h
+
 Developing using KVM API
 ========================

doc_new/developers/api_network_tests.rst

@@ -1,4 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later
 
+.. 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