Use Sphinx autodoc to create the API reference instead of Epydoc

.gitignore

@@ -7,6 +7,7 @@ wheelhouse
 wheels
 venvs
 venv
+doc/api/_build
 doc/html
 libs
 *.egg-info
@@ -16,9 +17,12 @@ libs
 *.pyd
 MANIFEST
 
+doc/s5/lxml-ep2008.html
 src/lxml/includes/lxml-version.h
 src/lxml/*.html
 src/lxml/html/*.c
+src/lxml/_elementpath.c
+src/lxml/builder.c
 src/lxml/etree.c
 src/lxml/etree.h
 src/lxml/etree_api.h
@@ -27,3 +31,4 @@ src/lxml/lxml.etree.h
 src/lxml/lxml.etree_api.h
 src/lxml/objectify.c
 src/lxml/lxml.objectify.c
+src/lxml/sax.c

.travis.yml

@@ -29,17 +29,20 @@ env:
 
 matrix:
   include:
-    - python: 3.7
-      env: STATIC_DEPS=false EXTRA_DEPS="coverage<5"
+    - python: 3.8
+      env:
+        - STATIC_DEPS=false
+        - EXTRA_DEPS="docutils pygments sphinx sphinx-rtd-theme"
+      script: make html
+    - python: 3.8
+      env:
+        - STATIC_DEPS=false
+        - EXTRA_DEPS="coverage<5"
     - python: 3.8
       env:
         - STATIC_DEPS=true
         - LIBXML2_VERSION=2.9.2  # minimum version requirements
         - LIBXSLT_VERSION=1.1.27
-    - python: pypy
-      env: STATIC_DEPS=false
-    - python: pypy3
-      env: STATIC_DEPS=false
     - python: 3.8
       env: STATIC_DEPS=false
       arch: arm64
@@ -52,6 +55,10 @@ matrix:
     - python: 3.8
       env: STATIC_DEPS=true
       arch: ppc64le
+    - python: pypy
+      env: STATIC_DEPS=false
+    - python: pypy3
+      env: STATIC_DEPS=false
   allow_failures:
     - python: pypy
     - python: pypy3

Makefile

@@ -106,14 +106,12 @@ ftest_inplace: inplace
 	$(PYTHON) test.py -f $(TESTFLAGS) $(TESTOPTS)
 
 apihtml: inplace
+	rm -fr doc/api/_build
 	rm -fr doc/html/api
-	@[ -x "`which epydoc`" ] \
-		&& (cd src && echo "Generating API docs ..." && \
-			PYTHONPATH=. epydoc -v --docformat "restructuredtext en" \
-			-o ../doc/html/api --exclude='[.]html[.]tests|[.]_' \
-			--exclude-introspect='[.]usedoctest' \
-			--name "lxml API" --url / lxml/) \
-		|| (echo "not generating epydoc API documentation")
+	@[ -x "`which sphinx-build`" ] \
+		&& (echo "Generating API docs ..." && \
+			make -C doc/api html) \
+		|| (echo "not generating Sphinx autodoc API documentation")
 
 website: inplace
 	PYTHONPATH=src:$(PYTHONPATH) $(PYTHON) doc/mkhtml.py doc/html . ${LXMLVERSION}
@@ -124,15 +122,11 @@ s5:
 	$(MAKE) -C doc/s5 slides
 
 apipdf: inplace
-	rm -fr doc/pdf
-	mkdir -p doc/pdf
-	@[ -x "`which epydoc`" ] \
-		&& (cd src && echo "Generating API docs ..." && \
-			PYTHONPATH=. epydoc -v --latex --docformat "restructuredtext en" \
-			-o ../doc/pdf --exclude='([.]html)?[.]tests|[.]_' \
-			--exclude-introspect='html[.]clean|[.]usedoctest' \
-			--name "lxml API" --url / lxml/) \
-		|| (echo "not generating epydoc API documentation")
+	rm -fr doc/api/_build
+	@[ -x "`which sphinx-build`" ] \
+		&& (echo "Generating API PDF docs ..." && \
+			make -C doc/api latexpdf) \
+		|| (echo "not generating Sphinx autodoc API PDF documentation")
 
 pdf: apipdf
 	$(PYTHON) doc/mklatex.py doc/pdf . ${LXMLVERSION}
@@ -164,6 +158,7 @@ docclean:
 	$(MAKE) -C doc/s5 clean
 	rm -f doc/html/*.html
 	rm -fr doc/html/api
+	rm -fr doc/api/_build
 	rm -fr doc/pdf
 
 realclean: clean docclean

doc/api/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" -d "$(BUILDDIR)/doctrees" ../html/api $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/api/conf.py

@@ -0,0 +1,52 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../src'))
+# For soupparser in lxml.html.ElementSoup module:
+sys.path.insert(1, os.path.abspath('../../src/lxml/html'))
+
+from lxml import __version__ as lxml_version
+
+# -- Project information -----------------------------------------------------
+
+project = 'lxml'
+copyright = '2020, lxml dev team'
+author = 'lxml dev team'
+version = lxml_version
+
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx_rtd_theme',
+]
+
+language = 'en'
+
+exclude_patterns = ['_build']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+
+html_logo = '../html/python-xml.png'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+
+# -- Extension configuration -------------------------------------------------
+
+autodoc_default_options = {
+    'ignore-module-all': True,
+    'private-members': True,
+}
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+#todo_include_todos = True

doc/api/index.rst

@@ -0,0 +1,18 @@
+lxml API Reference
+==================
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+
+   lxml
+   lxml.html
+   lxml.isoschematron
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/api/lxml.html.rst

@@ -0,0 +1,81 @@
+lxml.html
+=================
+
+lxml.html.ElementSoup module
+----------------------------
+
+.. automodule:: lxml.html.ElementSoup
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.builder module
+------------------------
+
+.. automodule:: lxml.html.builder
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.clean module
+----------------------
+
+.. automodule:: lxml.html.clean
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.defs module
+---------------------
+
+.. automodule:: lxml.html.defs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.diff module
+---------------------
+
+.. automodule:: lxml.html.diff
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.formfill module
+-------------------------
+
+.. automodule:: lxml.html.formfill
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.html5parser module
+----------------------------
+
+.. automodule:: lxml.html.html5parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.soupparser module
+---------------------------
+
+.. automodule:: lxml.html.soupparser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.html.usedoctest module
+---------------------------
+
+.. module:: lxml.html.usedoctest
+
+Doctest module for HTML comparison.
+
+Module contents
+---------------
+
+.. automodule:: lxml.html
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/lxml.isoschematron.rst

@@ -0,0 +1,10 @@
+lxml.isoschematron
+==========================
+
+Module contents
+---------------
+
+.. automodule:: lxml.isoschematron
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/api/lxml.rst

@@ -0,0 +1,73 @@
+lxml
+============
+
+lxml.ElementInclude module
+--------------------------
+
+.. automodule:: lxml.ElementInclude
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.builder module
+-------------------
+
+.. automodule:: lxml.builder
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.cssselect module
+---------------------
+
+.. automodule:: lxml.cssselect
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.doctestcompare module
+--------------------------
+
+.. automodule:: lxml.doctestcompare
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.etree module
+-----------------
+
+.. automodule:: lxml.etree
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.objectify module
+---------------------
+
+.. automodule:: lxml.objectify
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.sax module
+---------------
+
+.. automodule:: lxml.sax
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+lxml.usedoctest module
+----------------------
+
+.. module:: lxml.usedoctest
+
+Doctest module for XML comparison.
+
+Module contents
+---------------
+
+.. automodule:: lxml
+   :members:
+   :undoc-members:
+   :show-inheritance:

src/lxml/classlookup.pxi

@@ -504,7 +504,7 @@ cdef class PythonElementClassLookup(FallbackElementClassLookup):
     `lxml.etree` API (such as XPath, extended slicing or some
     iteration methods).
 
-    See http://codespeak.net/lxml/element_classes.html
+    See https://lxml.de/element_classes.html
     """
     def __cinit__(self):
         self._lookup_function = _python_class_lookup

src/lxml/html/__init__.py

@@ -37,7 +37,7 @@
     'document_fromstring', 'fragment_fromstring', 'fragments_fromstring', 'fromstring',
     'tostring', 'Element', 'defs', 'open_in_browser', 'submit_form',
     'find_rel_links', 'find_class', 'make_links_absolute',
-    'resolve_base_href', 'iterlinks', 'rewrite_links', 'open_in_browser', 'parse']
+    'resolve_base_href', 'iterlinks', 'rewrite_links', 'parse']
 
 
 import copy