docs: switch from Doxygen+Breathe to Hawkmoth
Hawkmoth is a Sphinx extension to incorporate documentation comments directly from source into Sphinx based documentation. It uses Clang for parsing, and generates Sphinx directives for documentation.
Arguably Hawkmoth is simpler to set up and use than Doxygen+Breathe, though it also has its limitations.
This merge request picks up @kusma's work in !23145 (closed). I took the liberty of changing authorship for three commits because I basically rewrote them. This is a draft, because it depends on some unreleased Hawkmoth features.
There are quite a few differences in Hawkmoth compared to Doxygen+Breathe, some of them good, some bad, and some ugly. Here's a list of things I encountered with the conversion:
[EDIT: I grouped these under headings, the bullets are almost the same.]
Things that are different with Hawkmoth (better or worse is subjective):
-
Documentation comments need to be pure reStructuredText. (There's limited javadoc support, but IMO it's better to go with pure rst to avoid conversion steps.)
-
The generated documentation style is slightly different. It's a matter of preference, but I think Hawkmoth results in better clarity.
Things that are better with Hawkmoth:
-
Macro documentation seems to work much better.
-
The documentation build is much less noisy and has no warnings.
-
The full documentation build is slightly faster, and incremental build is much faster.
Missing features or outright bugs in Hawkmoth (likely to be addressed in the future, but no guarantees on timelines):
-
enum documentation does not include the enumeration constant values. -
enumeration constants without a documentation comment will not be documented.
-
struct/union members without a documentation comment will not be documented. This holds recursively, and also for anonymous structs/enums; an undocumented struct/union member won't be recursed into for documented members. Adding an empty documentation comment /***/ will do the trick.
-
#92
bool type will show up as _Bool in documentation. This is unfortunate. <stdbool.h> defines bool instead of typedeffing, so _Bool is what Hawkmoth gets from Clang. There are ideas what to do, but this is the status quo. -
#174
Arrays documentation will have the compile-time value as dimensions even if the source code uses a symbolic size or macro constant. Also a bit meh. -
There's no grouping of any documentation using @{ and @}
Missing features in Hawkmoth (not likely to be addressed in the future)
-
structs/unions/enums that have no documentation comment will not be documented even if their members/enumerations have documentation comments. Adding an empty documentation comment /***/ will do the trick.
-
anonymous struct/union members will be present in documentation, and not flattened.
-
There is no automatic cross-reference generation for identifiers in documentation comments. Need to use appropriate :c:struct: reference or similar.
-
There is no automatic struct/union member cross-reference generation for the struct::member syntax. Need to use :c:member: reference or similar.
-
#190
typedef struct { ... } T; will need to have struct names to document T as a struct i.e. typedef struct T { ... } T; -
There's no support for /**< ... */ style after-the-symbol documentation comments.
But perhaps it's easiest just to look at the commits and the Hawkmoth generated documentation: https://people.freedesktop.org/~jani/mesa-hawkmoth/
In particular, in the documents under:
-
https://people.freedesktop.org/~jani/mesa-hawkmoth/vulkan/index.html
-
https://people.freedesktop.org/~jani/mesa-hawkmoth/nir/index.html
-
https://people.freedesktop.org/~jani/mesa-hawkmoth/isl/index.html
Full disclosure: Hawkmoth is my pet project.