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

Use sphinx-apidoc to create API reference #309

Merged
merged 12 commits into from Aug 4, 2020
Merged

Use sphinx-apidoc to create API reference #309

merged 12 commits into from Aug 4, 2020

Conversation

@cjmayo
Copy link
Contributor

@cjmayo cjmayo commented Jul 25, 2020

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.

@cjmayo cjmayo force-pushed the cjmayo:apidoc branch from fe5c76e to c7d1d5b Jul 25, 2020
Copy link
Member

@scoder scoder left a comment

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

Makefile Outdated
--exclude-introspect='[.]usedoctest' \
--name "lxml API" --url / lxml/) \
|| (echo "not generating epydoc API documentation")
apidoc: clean docclean

This comment has been minimized.

@scoder

scoder Jul 25, 2020
Member

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

This comment has been minimized.

@cjmayo

cjmayo Jul 26, 2020
Author Contributor

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?

This comment has been minimized.

@cjmayo

cjmayo Jul 27, 2020
Author Contributor

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
Copy link
Contributor Author

@cjmayo cjmayo commented Jul 29, 2020

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.

doc/api/conf.py Outdated Show resolved Hide resolved
@scoder
Copy link
Member

@scoder scoder commented Aug 4, 2020

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

This was referenced Mar 14, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
2 participants