From 67485efd654fd448c2adbb520a1fc1bca469c230 Mon Sep 17 00:00:00 2001
From: Erik Faye-Lund <kusmabite@gmail.com>
Date: Sat, 20 May 2023 12:50:03 +0200
Subject: [PATCH] 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       | 22 ++++++++++++++++++++++
 docs/gitlab-ci.yml |  4 ++--
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index c7a99047649..2f3fd7d3e82 100644
--- a/docs/conf.py
+++ b/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',
diff --git a/docs/gitlab-ci.yml b/docs/gitlab-ci.yml
index c96507f2651..ce044cdc080 100644
--- a/docs/gitlab-ci.yml
+++ b/docs/gitlab-ci.yml
@@ -8,8 +8,8 @@
     paths:
     - public/
   script:
-  - apk --no-cache add graphviz doxygen
-  - pip3 install sphinx===5.1.1 breathe===4.34.0 mako===1.2.3
+  - 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 hawkmoth===0.16.0
   - docs/doxygen-wrapper.py --out-dir=docs/doxygen_xml
   - sphinx-build -W -b $BUILDER docs public