Use Sphinx autodoc to create the API reference instead of Epydoc

[cjmayo]

Epydoc is Python 2 only and unmaintained.

---

I've had a go at producing the API reference with Sphinx. This is the output of sphinx-apidoc tweaked a little bit. Plus a few other commits that would probably be useful anyway.

To make for an easier review I've published it at: https://cjmayo.github.io/lxml/api/.

I've tried to create a straightforward replacement. I have updated the PDF generation, but not tested because I don't have all the LaTeX files installed.

[scoder]

Cool! Thanks!
I think there isn't anything in the travis setup currently that builds the docs, though. Probably worth adding a step for that as well – or a dedicated build target?

[scoder]

That suggests that it's not worth documenting.

[cjmayo]

OK. Reverted and dropped from the documentation.

[bkline]

It certainly looks prettier, but if this is a replacement for https://lxml.de/api/ I'm not finding everything. It's possible I'm not looking in the right places, but where for example is documentation for the members of _Element?

[scoder]

I think tests were previously only included by accident. I think it's useless to add them here.

[cjmayo]

Removed tests.

[scoder]

Isn't there a way to generate these index files automatically? They seem trivial, and that's unlikely to change. But when new modules or packages are added, it's annoying to have to remember and add them here.

[cjmayo]

There is sphinx-autogen [1] which can generate module rst files based on one simple top-level rst. You have to have summaries, which maybe is OK, but I can't see how to get the summaries to include private classes like lxml.etree._Element.

[1] https://www.sphinx-doc.org/en/master/man/sphinx-autogen.html

[scoder]

Does it not take the default "autodoc" options into account?

[cjmayo]

In the autodoc sections yes, but not in the autosummary tables

Classes

AncestorsIterator(self, node[, tag])	Iterates over the ancestors of an element (from parent to parent).
AttributeBasedElementClassLookup(self, …)	Checks an attribute of an Element and looks up the value in a class dictionary.
C14NWriterTarget	Canonicalization writer target for the XMLParser.
CDATA(data)	CDATA factory.
...

[cjmayo]

Maybe it is possible to use sphinx-apidoc every time and forget about the summaries, it does take quite a few options, including --private.

[cjmayo]

Maybe it is possible to use sphinx-apidoc every time and forget about the summaries, it does take quite a few options, including --private.

Created #309 using this approach.

[scoder]

where for example is documentation for the members of _Element ?

Yeah, "private" classes in lxml are not all that private, really. They are not intended to be instantiated by users, but they are part of the API and need to be included in the API documentation.

[cjmayo]

I think there isn't anything in the travis setup currently that builds the docs, though. Probably worth adding a step for that as well – or a dedicated build target?

Added a make html to Travis.

I've just added commits here, I don't know what your preference is for tidying up with rebasing and squashing.

[cjmayo]

where for example is documentation for the members of _Element ?

Yeah, "private" classes in lxml are not all that private, really. They are not intended to be instantiated by users, but they are part of the API and need to be included in the API documentation.

Needs :ignore-module-all: as well I think because _Element is not in lxml.etree.__all__. Added and moved down to extensions section.

[scoder]

Closing, superseded by #309.