-
-
Notifications
You must be signed in to change notification settings - Fork 572
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
Conversation
Epydoc is Python 2 only and unmaintained. sphinx-apidoc is run before the build step, to avoid duplicate entries being created.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is what needs the inplace
lxml build as a dependency, not the other targets, right?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
…lly use "inplace3" since that's what we use.
… global installation.
Unfortunately I still get the same result with 61d135e. I've tried It is the modules that have the shared libraries that are duplicated. |
Let's get this in and fix the rest later. Thanks a lot! |
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.