doc: tips: dealing with generated headers

doc/tips.rst

@@ -59,3 +59,21 @@ The Sphinx alternative is :external+sphinx:rst:dir:`literalinclude`. The
 .. _@include: https://www.doxygen.nl/manual/commands.html#cmdinclude
 
 .. _@snippet: https://www.doxygen.nl/manual/commands.html#cmdsnippet
+
+Dealing With Generated Headers
+------------------------------
+
+Sometimes your regular build process generates headers that are then included in
+source code. This can be a problem for the documentation build, as they are
+typically not available.
+
+Instead of adding lots of conditional compilation, you might want to consider
+adding a directory for header stubs used only for the documentation build. For
+example, if you have a ``generated-header.h``, place that at
+``docs/header-stubs/`` directory, and add ``-Idocs/header-stubs/`` to
+:py:data:`hawkmoth_clang`.
+
+Your regular build will then use the generated file, and the documentation build
+will use the static file. The static file may be empty, or contain just the
+minimal types and macros to avoid compiler errors, or you can add full blown
+code documentation in the header stubs.