Contributor

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?

Contributor Author

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 lxml.etree module starts with 6 pages of exceptions which doesn't make for the most nicest of reads.

Member

Could not test the docs because I'm hitting cython/cython#3876,

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.

Member

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 lxml.etree module starts with 6 pages of exceptions which doesn't make for the most nicest of reads.

Don't know if there is a way in apidoc to change the ordering, but there probably is. I agree that exceptions certainly aren't the most interesting part. Alphabetic ordering is helpful, though, so maybe the normal classes should just go first, followed by functions, followed by exceptions.

Also lxml.etree, lxml.html and lxml.objectify should rather be shown at the top of the list, in that order.

Contributor Author

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 lxml.etree module starts with 6 pages of exceptions which doesn't make for the most nicest of reads.

Don't know if there is a way in apidoc to change the ordering, but there probably is. I agree that exceptions certainly aren't the most interesting part.

Sadly I don't think there's a way for apidoc to do that, hence the query about committing the files it generates, instead of running apidoc on doc build it'd just be used once to generate the "initial" state (as a scaffolding tool), then those would be edited directly.

The code being committed can still use autodoc though.

Contributor Author

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 lxml.etree.set_element_class_lookup?

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 _elementFactory, which calls LOOKUP_ELEMENT_CLASS, which is the object set by `set_element_class_lookup. So that is the first step, and (optionally) calling the parser's lookup' (or not) is its responsibility.

Member

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.

Member

Thanks

Contributor Author

Haha nah thank you, the final version is quite a bit better than the original proposal. Cheers.

Contributor Author

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.

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.