Use sphinx-apidoc to create API reference

[cjmayo]

Epydoc is Python 2 only and unmaintained.

sphinx-apidoc is run before the build step, to avoid duplicate entries
being created.

---

This is an alternative to #308 that generates the rst files every time.

[scoder]

Haven't looked at the generated docs, but it generally looks good to me.

[scoder]

I think this is what needs the inplace lxml build as a dependency, not the other targets, right?

[cjmayo]

sphinx-apidoc appears to only scan files, which is how I read:

Warning

sphinx-apidoc generates source files that use sphinx.ext.autodoc to document all found modules. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.

https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

and the build inplace causes sphinx-apidoc to create duplicate entries

e.g.

--- lxml.rst
+++ lxml.rst
@@ -18,11 +18,16 @@
 
    lxml.ElementInclude
    lxml._elementpath
+   lxml._elementpath
+   lxml.builder
    lxml.builder
    lxml.cssselect
    lxml.doctestcompare
    lxml.etree
+   lxml.etree
    lxml.objectify
+   lxml.objectify
+   lxml.sax
    lxml.sax
 
 Module contents

Looks like excluding .so files avoids this, by adding "*.so":

sphinx-apidoc -e -P -T -o doc/api src/lxml "*includes" "*tests" "*pyclasslookup.py" "*usedoctest.py" "*html/_html5builder.py" "*.so"

That's a possibility but still needs a separate apidoc target to support apidf as well. I'm not sure if it gains anything?

[cjmayo]

The duplication seems to be because there is a system copy of lxml installed. But without a system lxml, sphinx-apidoc appears to work without compiling lxml.

[cjmayo]

Unfortunately I still get the same result with 61d135e.

I've tried python -m sphinx.ext.apidoc instead of sphinx-apidoc.

It is the modules that have the shared libraries that are duplicated.

[scoder]

Let's get this in and fix the rest later. Thanks a lot!