Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate Python stubs with m.css for IDE autocompletion and type checking #2477

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

mosra
Copy link
Collaborator

@mosra mosra commented Sep 28, 2024

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:

  • 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.

@facebook-github-bot facebook-github-bot added the CLA Signed Do not delete this pull request or issue due to inactivity. label Sep 28, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Do not delete this pull request or issue due to inactivity.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants