diff --git a/.gitignore b/.gitignore index d10849a01..e37931b7f 100644 --- a/.gitignore +++ b/.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 diff --git a/.travis.yml b/.travis.yml index 628ee76ff..f2cf21276 100644 --- a/.travis.yml +++ b/.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 diff --git a/Makefile b/Makefile index 7eb976cd0..81dfc03ad 100644 --- a/Makefile +++ b/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 diff --git a/doc/api/Makefile b/doc/api/Makefile new file mode 100644 index 000000000..c717f8b78 --- /dev/null +++ b/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) diff --git a/doc/api/conf.py b/doc/api/conf.py new file mode 100644 index 000000000..8d1b082a2 --- /dev/null +++ b/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 diff --git a/doc/api/index.rst b/doc/api/index.rst new file mode 100644 index 000000000..8661e8cfe --- /dev/null +++ b/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` diff --git a/doc/api/lxml.html.rst b/doc/api/lxml.html.rst new file mode 100644 index 000000000..57305d7c2 --- /dev/null +++ b/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: diff --git a/doc/api/lxml.isoschematron.rst b/doc/api/lxml.isoschematron.rst new file mode 100644 index 000000000..e6c7d37b9 --- /dev/null +++ b/doc/api/lxml.isoschematron.rst @@ -0,0 +1,10 @@ +lxml.isoschematron +========================== + +Module contents +--------------- + +.. automodule:: lxml.isoschematron + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/api/lxml.rst b/doc/api/lxml.rst new file mode 100644 index 000000000..e4a75e18f --- /dev/null +++ b/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: diff --git a/src/lxml/classlookup.pxi b/src/lxml/classlookup.pxi index 89302251d..137e111ab 100644 --- a/src/lxml/classlookup.pxi +++ b/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 diff --git a/src/lxml/html/__init__.py b/src/lxml/html/__init__.py index 30a2ed0ee..45421fccb 100644 --- a/src/lxml/html/__init__.py +++ b/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 diff --git a/src/lxml/html/defs.py b/src/lxml/html/defs.py index b21a11341..1b3a75b36 100644 --- a/src/lxml/html/defs.py +++ b/src/lxml/html/defs.py @@ -2,9 +2,11 @@ # (probably in a test; this may not match the DTD exactly, but we # should document just how it differs). -# Data taken from http://www.w3.org/TR/html401/index/elements.html -# and http://www.w3.org/community/webed/wiki/HTML/New_HTML5_Elements -# for html5_tags. +""" +Data taken from https://www.w3.org/TR/html401/index/elements.html +and https://www.w3.org/community/webed/wiki/HTML/New_HTML5_Elements +for html5_tags. +""" empty_tags = frozenset([ 'area', 'base', 'basefont', 'br', 'col', 'frame', 'hr', diff --git a/src/lxml/sax.py b/src/lxml/sax.py index 299c235e8..02ee3bf39 100644 --- a/src/lxml/sax.py +++ b/src/lxml/sax.py @@ -9,7 +9,7 @@ Use the `ElementTreeProducer` class or the `saxify()` function to fire the SAX events of an ElementTree against a SAX ContentHandler. -See http://codespeak.net/lxml/sax.html +See https://lxml.de/sax.html """ from __future__ import absolute_import diff --git a/src/lxml/tests/test_xmlschema.py b/src/lxml/tests/test_xmlschema.py index 921ed800c..c5653c1e5 100644 --- a/src/lxml/tests/test_xmlschema.py +++ b/src/lxml/tests/test_xmlschema.py @@ -66,8 +66,10 @@ def test_xmlschema_error_log_path(self): for a _LogEntry object (or even a node for which to determine a path), but at least when this test was created schema validation errors always got a node and an XPath value. If that ever changes, - we can modify this test to something like: + we can modify this test to something like:: + self.assertTrue(error_path is None or tree_path == error_path) + That way, we can at least verify that if we did get a path value it wasn't bogus. """