Based off #2415, but this time with m.css instead of pybind11-stubgen. Which ensures that the output is consistent with online docs, includes various special casing for Habitat, module renaming, etc.
I'm marking it as a draft because even though it works quite well on my own Magnum bindings, there's of course an infinite amount of possibilities where it could break on other code, after all it's just about two weeks of work. Important differences to the previous approach:
The bindings are generated for the whole Habitat project, instead of just the bindings. My thinking is that it'll make more sense this way, because using the __all__ properties you can control what gets shown in IDE autocompletion hints and thus better drive users to the desirable way of use, matching the actual documentation.
As far as my local testing goes, it should be capable of deciphering more pybind11 annotations than what pybind11-stubgen did, and for those it fails to decipher, it'll fail gracefully. It also exposes enums as actual enums, without having to do something extra.
There are no docstrings at the moment. Right now my focus was on producing code that actually makes sense and can be interpreted by Python. Putting docstrings into the output is relatively trivial in comparison, I'll do that later.
Also, because it's made by the same thing as the online docs, there are a few possibilities. It can be just the one-line summaries, it can be all of it, but it can also be a summary + a link to online docs. Your choice, let me know.
You'll probably want to have stubs for Magnum bindings as well, I guess? For those I still have a bunch of local patches so it won't work for you (it asserts otherwise), but here's an archive of them pregenerated: corrade+magnum-stubs.zip
Eventually, the tool will be capable of producing just the stubs, without also generating the HTML output (and, hopefully, no longer relying on docutils etc.). Right now it does both, so it's slower than it could theoretically be.
Looking forward for your feedback. Let me know once you stumble upon something that feels off.
Based off #2415, but this time with m.css instead of pybind11-stubgen. Which ensures that the output is consistent with online docs, includes various special casing for Habitat, module renaming, etc.
Work-in-progress documentation for the stub generator.
I'm marking it as a draft because even though it works quite well on my own Magnum bindings, there's of course an infinite amount of possibilities where it could break on other code, after all it's just about two weeks of work. Important differences to the previous approach:
__all__properties you can control what gets shown in IDE autocompletion hints and thus better drive users to the desirable way of use, matching the actual documentation.docutilsetc.). Right now it does both, so it's slower than it could theoretically be.Looking forward for your feedback. Let me know once you stumble upon something that feels off.