Sphinx-builder to statically generate the autodoc expanded files

[LecrisUT]

As a way to break the dependency on compilers, I am suggesting having a way to generate all of the contents used by the autodoc and then have a switch that would either read those contents (for RTD building), or use the current approach (for local development).

The generated files here could either be rst/md files, or just a json file to be a lookaside cache.

I suggest the interface being a sphinx builder because it can then easily slot in people's CI system along with linkcheck and others, but having it always generated is also an option.

[jnikula]

Basically the idea would be that a regular run would store the results, which could then be checked in version control, and included with the extension configured not to depend on clang.

It's obviously doable, and way back we actually had something like that for Hawkmoth's own documentation. There was no caching of the results, because all the examples were already part of the test suite, and we could just include those in place. We gave up on it, because it was an extra complication, we figured out how to use clang on RTD, and switched to primarily hosting the docs in github pages (though RTD is still there).

I'm not super keen on implementing this, though.

The hours I have to put into this project are a scarce resource. I want to keep the codebase lean and manageable, and focus on making a tight set of features work well. There are a bunch of feature requests I do want to attend to, but this one doesn't immediately strike me as one that's essential.

I guess if the primary issue is people not being able to build the docs at all without libclang and its bindings (which I admit can be difficult to set up), one compromise could be allowing everything else to build, and adding placeholders for Hawkmoth directives. You don't get the full API docs, but you can work on docs without installing a whole toolchain.