Integrate in-code documentation into Mesa docs
I've begun adding a bunch of additional ISL documentation in !11366 (merged). Much of the ISL docs are currently in isl.h and I'd really like to keep docs with code as much as possible as it allows you to see what's going on without having to have a web browser open. Most of the new .rst files added as part of !11366 (merged) are large blocks of prose which help tie it all together in a cohesive way.
To be clear, I'm NOT suggesting we run doxygen on the tree, dump that into the docs folder, and pretend we've documented Mesa. I'm looking for a far more targetted approach like what I've done with ISL which aims to not only provide function prototype documentation but also document over-all themes and approaches. I'd also like to keep the documentation for things like ISL and NIR organized a bit, maybe better than we've kept headers organized.
The current solution in !11366 (merged) is to use doxygen to scrape the code and breathe to integrate with sphinx. This is terrible for three big reasons:
- I really don't like the doxygen comment format and neither does anyone else I've talked to.
- Doxygen is Markdown-based while Sphinx is based on reStructuredText. While both work, constantly switching between the two is horrible.
- Doxygen is big and clunky and, the way breathe is currently designed, has to be run as a separate step with hard-coded paths.
- Wayland gets around the hard-coded paths by integrating with meson but that raises its own set of issues.
Unfortunately, the other options out there currently, aren't really sufficient for Mesa's needs today. Other options include:
- kernel-doc: This clearly works at scale but it has its own problems:
- It's still something of a kludge, depending on a lot of perl code
- It's not well-packaged so we'd have to copy+paste said perl code into the Mesa tree
- It is based on the kerneldoc format which, while functional, isn't compatible with most of the code comments already in the Mesa tree. Something that at least tries to understand doxygen would make improving our docs less painful.
- hawkmoth: Written by our own @jani, this project extracts doc comments from functions using clang. The primary issue is that it doesn't support pulling docs for a single function or struct at a time and can only document whole files. I'm also not sure how it would do with C++
-
sphinx-c-autodoc: This was based on hawkmoth and does provide single-function documentation. However, there are a couple issues:
- it's unclear how well-maintained the project or whether or not they'd be interested in growing the features we need. There are a total of 14 issues filed by 4 people and zero pull requests.
- I found a pretty show-stopping bug in my first attempt at using it: It doesn't handle blank lines in code comments properly so you can't write a multi-paragraph code comment. If it couldn't get that right, what else is hiding in there?
I'm very much open to suggestions. I think my personal preference, and @daniels seemed to agree on IRC, was that if hawkmoth could grow the features we need, I'd drop doxygen in favor of it in a heartbeat. We don't necessarily need something complicated; we need something reliable.
Thoughts? Opinions?