-
-
Notifications
You must be signed in to change notification settings - Fork 563
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
Add warning about the global set_element_class_lookup
#341
Conversation
It's a bit of an attractive nuisance, as it basically turns off parser-specific class lookups.
Also the new doc is... a bit of a mess. Would it be OK to submit PRs to commit the apidoc-generated stuff and start hand-crafting the documents in order to make them more logical and stuff? e.g. the |
That's long solved, though. That was a problem in 0.29.22, even the legacy stable release of Cython is at 0.29.28 now. |
Don't know if there is a way in Also |
Sadly I don't think there's a way for The code being committed can still use autodoc though. |
Thinking about it further, maybe it would (also?) be a good idea to clarify that the global element lookup is really the first step for resolution? And remove the word "default" from the docstring of That kinda gives the impression that it is the fallback, but it's the other way around right? When an element proxy needs to be created, lxml invokes |
I'd rather not commit generated files. They just bloat the history, complicate merges and are annoying to work with in various ways. The way to control API documentation in Sphinx seems to be module files and/or TOC files. There are also various hacks that people have come up with. I'm not particularly tied to sphinx-apidoc. If there's a different solution, I'm open. |
Thanks |
Haha nah thank you, the final version is quite a bit better than the original proposal. Cheers. |
Committing generated files is an issue when regularly re-exporting isn't it? Here the output of apidoc would provide a skeleton / starting point, then it wouldn't be used anymore, so there's no more complication than if the initial state had been written by hand. That's how I've used it in the past anyway. Pretty much what the second answer suggests in your link. |
It's a bit of an attractive nuisance, as it basically turns off parser-specific class lookups, which can be surprising to people who have not looked up the mechanism in details (it certainly surprised me).
Also set
inherited-members
in the autodoc config: it's a bit dodgy but because_BaseParser
is@cpython.internal
it looks like autodoc can't see it at all, and so anything defined on_BaseParser
is invisible in the new rst-based doc.Could not test the docs because I'm hitting cython/cython#3876, does one of the statuses provide a doc to look at?