Fix reference targets in Sphinx documentation (#562)

Fixes #548
html5lib · Mar 1, 2023 · 5c30ac3 · 5c30ac3
1 parent ff7fa37
commit 5c30ac3
Show file tree

Hide file tree

Showing 8 changed files with 61 additions and 51 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -19,7 +19,8 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.viewcode',
+              'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -92,6 +93,13 @@
 ]
 
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'lxml': ('https://lxml.de/apidoc/', None),
+    'chardet': ('https://chardet.readthedocs.io/en/latest/', None),
+}
+
+
 class CExtMock(object):
     """Required for autodoc on readthedocs.org where you cannot build C extensions."""
     def __init__(self, *args, **kwargs):

diff --git a/doc/html5lib.filters.rst b/doc/html5lib.filters.rst
@@ -1,56 +1,61 @@
 filters Package
 ===============
 
-:mod:`base` Module
--------------------
+``base`` Module
+----------------
 
 .. automodule:: html5lib.filters.base
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`alphabeticalattributes` Module
-------------------------------------
+.. autoclass:: html5lib.filters.base.Filter
+    :members:
+    :show-inheritance:
+    :special-members: __init__
+
+``alphabeticalattributes`` Module
+---------------------------------
 
 .. automodule:: html5lib.filters.alphabeticalattributes
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`inject_meta_charset` Module
----------------------------------
+``inject_meta_charset`` Module
+------------------------------
 
 .. automodule:: html5lib.filters.inject_meta_charset
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`lint` Module
-------------------
+``lint`` Module
+---------------
 
 .. automodule:: html5lib.filters.lint
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`optionaltags` Module
---------------------------
+``optionaltags`` Module
+-----------------------
 
 .. automodule:: html5lib.filters.optionaltags
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`sanitizer` Module
------------------------
+``sanitizer`` Module
+--------------------
 
 .. automodule:: html5lib.filters.sanitizer
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`whitespace` Module
-------------------------
+``whitespace`` Module
+---------------------
 
 .. automodule:: html5lib.filters.whitespace
     :members:

diff --git a/doc/html5lib.rst b/doc/html5lib.rst
@@ -4,29 +4,34 @@ html5lib Package
 .. automodule:: html5lib
     :members: __version__
 
-:mod:`constants` Module
------------------------
+``constants`` Module
+--------------------
 
 .. automodule:: html5lib.constants
     :members:
     :show-inheritance:
 
-:mod:`html5parser` Module
--------------------------
+``html5parser`` Module
+----------------------
 
 .. automodule:: html5lib.html5parser
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`serializer` Module
-------------------------
+``serializer`` Module
+---------------------
 
 .. automodule:: html5lib.serializer
     :members:
     :show-inheritance:
     :special-members: __init__
 
+.. autoclass:: html5lib.serializer.HTMLSerializer
+    :members:
+    :show-inheritance:
+    :special-members: __init__
+
 Subpackages
 -----------
 

diff --git a/doc/html5lib.treeadapters.rst b/doc/html5lib.treeadapters.rst
@@ -1,9 +1,6 @@
 treeadapters Package
 ====================
 
-:mod:`~html5lib.treeadapters` Package
--------------------------------------
-
 .. automodule:: html5lib.treeadapters
     :members:
     :show-inheritance:

diff --git a/doc/html5lib.treebuilders.rst b/doc/html5lib.treebuilders.rst
@@ -1,40 +1,37 @@
 treebuilders Package
 ====================
 
-:mod:`treebuilders` Package
----------------------------
-
 .. automodule:: html5lib.treebuilders
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`base` Module
--------------------
+``base`` Module
+---------------
 
 .. automodule:: html5lib.treebuilders.base
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`dom` Module
------------------
+``dom`` Module
+--------------
 
 .. automodule:: html5lib.treebuilders.dom
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`etree` Module
--------------------
+``etree`` Module
+----------------
 
 .. automodule:: html5lib.treebuilders.etree
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`etree_lxml` Module
-------------------------
+``etree_lxml`` Module
+---------------------
 
 .. automodule:: html5lib.treebuilders.etree_lxml
     :members:

diff --git a/doc/html5lib.treewalkers.rst b/doc/html5lib.treewalkers.rst
@@ -1,48 +1,45 @@
 treewalkers Package
 ===================
 
-:mod:`treewalkers` Package
---------------------------
-
 .. automodule:: html5lib.treewalkers
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`base` Module
-------------------
+``base`` Module
+---------------
 
 .. automodule:: html5lib.treewalkers.base
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`dom` Module
------------------
+``dom`` Module
+--------------
 
 .. automodule:: html5lib.treewalkers.dom
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`etree` Module
--------------------
+``etree`` Module
+----------------
 
 .. automodule:: html5lib.treewalkers.etree
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`etree_lxml` Module
-------------------------
+``etree_lxml`` Module
+---------------------
 
 .. automodule:: html5lib.treewalkers.etree_lxml
     :members:
     :show-inheritance:
     :special-members: __init__
 
-:mod:`genshi` Module
---------------------
+``genshi`` Module
+-----------------
 
 .. automodule:: html5lib.treewalkers.genshi
     :members:

diff --git a/doc/movingparts.rst b/doc/movingparts.rst
@@ -15,9 +15,9 @@ Tree builders
 The parser reads HTML by tokenizing the content and building a tree that
 the user can later access. html5lib can build three types of trees:
 
-* ``etree`` - this is the default; builds a tree based on :mod:`xml.etree`,
-  which can be found in the standard library. Whenever possible, the
-  accelerated ``ElementTree`` implementation (i.e.
+* ``etree`` - this is the default; builds a tree based on
+  :mod:`xml.etree.ElementTree`, which can be found in the standard library.
+  Whenever possible, the accelerated ``ElementTree`` implementation (i.e.
   ``xml.etree.cElementTree`` on Python 2.x) is used.
 
 * ``dom`` - builds a tree based on :mod:`xml.dom.minidom`.

diff --git a/html5lib/treebuilders/base.py b/html5lib/treebuilders/base.py
@@ -121,6 +121,7 @@ def hasContent(self):
 
 class ActiveFormattingElements(list):
     def append(self, node):
+        """Append node to the end of the list."""
         equalCount = 0
         if node != Marker:
             for element in self[::-1]: