Fix include paths

doc/extension.rst

@@ -56,10 +56,38 @@ See also additional configuration options in the :ref:`built-in extensions
    :type: str
 
    The default transform parameter to be passed to the
-   :event:`hawkmoth-process-docstring` event. It can be overriden with the
+   :event:`hawkmoth-process-docstring` event. It can be overridden with the
    ``transform`` option of the :ref:`directives <directives>`. Defaults to
    ``None``.
 
+.. py:data:: hawkmoth_compiler
+   :type: str
+
+   The (path to the) default compiler used by the project. This is used to
+   determine the exact options needed to parse the code files by libclang
+   provided the relevant options are enabled in :data:`hawkmoth_autoconf`.
+
+   Notably, it allows hawkmoth to override libclang's default search path for
+   system headers with those of the specified compiler.
+
+   This presumes the compiler supports being called as
+   ``<compiler> -x <c|c++> -E -Wp,-v /dev/null``.
+
+   Defaults to ``clang``, which may differ from libclang's own default includes.
+   It will use libclang's defaults if set to ``None`` though.
+
+   This is a shortcut to specify ``-nostdinc -I<dir 1> ... -I<dir n>`` in
+   :data:`hawkmoth_clang` with the search directories of the specified compiler.
+
+.. py:data:: hawkmoth_autoconf
+   :type: list
+
+   List of options that control the automatic configuration features of
+   hawkmoth. Currently supported options:
+
+   * ``'stdinc'``: override the standard include paths of libclang with those of
+     the specified compiler (see :data:`hawkmoth_compiler`).
+
 .. py:data:: hawkmoth_clang
    :type: list
 
@@ -73,18 +101,6 @@ See also additional configuration options in the :ref:`built-in extensions
 
       hawkmoth_clang = ['-I/path/to/include', '-DHAWKMOTH']
 
-   Hawkmoth provides a convenience helper for querying the include path from the
-   compiler, and providing them as ``-I`` options:
-
-   .. code-block:: python
-
-      from hawkmoth.util import compiler
-
-      hawkmoth_clang = compiler.get_include_args()
-
-   You can also pass in the compiler to use, for example
-   ``get_include_args('gcc')``.
-
 .. py:data:: hawkmoth_clang_c
    :type: list
 

src/hawkmoth/__init__.py

@@ -19,6 +19,7 @@
 from sphinx.util.docutils import switch_source_input, SphinxDirective
 from sphinx.util import logging
 
+from hawkmoth.util import compiler
 from hawkmoth.parser import parse, ErrorLevel
 from hawkmoth.util import strutil
 from hawkmoth import docstring
@@ -39,6 +40,31 @@ class _AutoBaseDirective(SphinxDirective):
     _domain: Optional[str] = None
     _docstring_types: Optional[list[type[docstring.Docstring]]] = None
 
+    def __init__(self, name, arguments, options,
+                 content, lineno, content_offset,
+                 block_text, state, state_machine):
+
+        super().__init__(name, arguments, options,
+                         content, lineno, content_offset,
+                         block_text, state, state_machine)
+
+        cpath = self.env.config.hawkmoth_compiler
+        autoconf = self.env.config.hawkmoth_autoconf
+
+        ignored_options = [x for x in autoconf if x not in ['stdinc']]
+        if len(ignored_options) > 0:
+            self.logger.warning(f'autoconf: {ignored_options} unsupported option(s) ignored')
+
+        self._clang_args_post = []
+        if 'stdinc' in autoconf:
+            if cpath:
+                if self._domain == 'c':
+                    self._clang_args_post = compiler.get_include_args(cpath, 'c')
+                else:
+                    self._clang_args_post = compiler.get_include_args(cpath, 'c++')
+            else:
+                self.logger.warning('autoconf: \'stdinc\' option ignored (missing compiler)')
+
     def __display_parser_diagnostics(self, errors):
         # Map parser diagnostic level to Sphinx level name
         log_level_map = {
@@ -56,15 +82,14 @@ def __display_parser_diagnostics(self, errors):
     def __get_clang_args(self):
         clang_args = []
 
-        clang_args.extend(self.env.config.hawkmoth_clang.copy())
-
         if self._domain == 'c':
             clang_args.extend(self.env.config.hawkmoth_clang_c.copy())
         else:
             clang_args.extend(self.env.config.hawkmoth_clang_cpp.copy())
 
         clang_args.extend(self.options.get('clang', []))
 
+        clang_args.extend(self._clang_args_post)
         return clang_args
 
     def __parse(self, filename):
@@ -358,6 +383,8 @@ def setup(app):
     app.require_sphinx('3.0')
 
     app.add_config_value('hawkmoth_root', app.confdir, 'env', [str])
+    app.add_config_value('hawkmoth_compiler', 'clang', 'env', [str, type(None)])
+    app.add_config_value('hawkmoth_autoconf', ['stdinc'], 'env', [list])
     app.add_config_value('hawkmoth_clang', [], 'env', [list])
     app.add_config_value('hawkmoth_clang_c', [], 'env', [list])
     app.add_config_value('hawkmoth_clang_cpp', [], 'env', [list])