docs: prepare for hawkmoth

Hawkmoth is a Sphinx-extension that uses Clang to directly parse C code
for automatic documentation of C/C++ code, similar to what Doxygen does.

However, Doxygen is rather clunky to integrate into the build process,
so let's start switching over to Hawkmoth instead.

As Sphinx does not have syntax for describing parameter direction, add
an rst_prolog with rst replacements for them.

Reviewed-by: Jani Nikula <jani@nikula.org>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507>

docs/conf.py

@@ -21,6 +21,8 @@
 import os
 import sys
 
+from hawkmoth.util import compiler
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -40,6 +42,7 @@ extensions = [
     'bootstrap',
     'breathe',
     'formatting',
+    'hawkmoth',
     'nir',
     'redirects',
     'sphinx.ext.graphviz',
@@ -214,6 +217,25 @@ texinfo_documents = [
 
 graphviz_output_format = 'svg'
 
+# -- Options for hawkmoth -------------------------------------------------
+
+hawkmoth_root = os.path.abspath('..')
+hawkmoth_clang = [
+  '-Iinclude/',
+  '-Isrc/',
+  '-DHAVE_STRUCT_TIMESPEC',
+  '-DHAVE_PTHREAD',
+  '-DHAVE_ENDIAN_H',
+]
+hawkmoth_clang.extend(compiler.get_include_args())
+
+# helpers for definining parameter direction
+rst_prolog = '''
+.. |in| replace:: **[in]**
+.. |out| replace:: **[out]**
+.. |inout| replace:: **[inout]**
+'''
+
 # -- Options for breathe --------------------------------------------------
 breathe_projects = {
     'mesa' : 'doxygen_xml',

docs/gitlab-ci.yml

@@ -8,8 +8,8 @@
     paths:
     - public/
   script:
-  - apk --no-cache add graphviz doxygen
+  - apk --no-cache add graphviz doxygen py3-clang clang-dev musl-dev linux-headers
-  - pip3 install sphinx===5.1.1 breathe===4.34.0 mako===1.2.3
+  - pip3 install sphinx===5.1.1 breathe===4.34.0 mako===1.2.3 hawkmoth===0.16.0
   - docs/doxygen-wrapper.py --out-dir=docs/doxygen_xml
   - sphinx-build -W -b $BUILDER docs public