sphinx-toolbox · domdfcoding · Aug 3, 2022 · Jul 28, 2022 · Aug 2, 2022 · Aug 2, 2022
diff --git a/.github/workflows/python_ci.yml b/.github/workflows/python_ci.yml
@@ -28,14 +28,14 @@ jobs:
       fail-fast: False
       matrix:
         config:
-          - {python-version: "3.7", testenvs: "py37-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.8", testenvs: "py38-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.9", testenvs: "py39-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.10", testenvs: "py310-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.11.0-beta.3", testenvs: "py311-dev-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0}", experimental: True}
+          - {python-version: "3.7", testenvs: "py37-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.8", testenvs: "py38-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.9", testenvs: "py39-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.10", testenvs: "py310-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.11.0-beta.3", testenvs: "py311-dev-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0,5.1}", experimental: True}
 
     steps:
       - name: Checkout 🛎️

diff --git a/.github/workflows/python_ci_linux.yml b/.github/workflows/python_ci_linux.yml
@@ -29,14 +29,14 @@ jobs:
       fail-fast: False
       matrix:
         config:
-          - {python-version: "3.7", testenvs: "py37-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.8", testenvs: "py38-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.9", testenvs: "py39-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.10", testenvs: "py310-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.11.0-beta.3", testenvs: "py311-dev-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0}", experimental: True}
+          - {python-version: "3.7", testenvs: "py37-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.8", testenvs: "py38-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.9", testenvs: "py39-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.10", testenvs: "py310-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.11.0-beta.3", testenvs: "py311-dev-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0,5.1}", experimental: True}
 
     steps:
       - name: Checkout 🛎️

diff --git a/.github/workflows/python_ci_macos.yml b/.github/workflows/python_ci_macos.yml
@@ -28,14 +28,14 @@ jobs:
       fail-fast: False
       matrix:
         config:
-          - {python-version: "3.7", testenvs: "py37-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.8", testenvs: "py38-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.9", testenvs: "py39-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.10", testenvs: "py310-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: False}
-          - {python-version: "3.11.0-beta.3", testenvs: "py311-dev-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0},build", experimental: True}
-          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0}", experimental: True}
+          - {python-version: "3.7", testenvs: "py37-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.8", testenvs: "py38-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.9", testenvs: "py39-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.10", testenvs: "py310-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: False}
+          - {python-version: "3.11.0-beta.3", testenvs: "py311-dev-sphinx{3.2,3.3,3.4,3.5,4.0,4.1,4.2,4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.7", testenvs: "pypy37-sphinx{4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.8", testenvs: "pypy38-sphinx{4.3,4.4,4.5,5.0,5.1},build", experimental: True}
+          - {python-version: "pypy-3.9", testenvs: "pypy39-sphinx{4.3,4.4,4.5,5.0,5.1}", experimental: True}
 
     steps:
       - name: Checkout 🛎️

diff --git a/doc-source/extensions/tweaks/revert_footnote_style.rst b/doc-source/extensions/tweaks/revert_footnote_style.rst
@@ -0,0 +1,9 @@
+.. latex:clearpage::
+
+=================================================
+:mod:`.tweaks.revert_footnote_style`
+=================================================
+
+.. automodule:: sphinx_toolbox.tweaks.revert_footnote_style
+
+.. clearpage::
diff --git a/repo_helper.yml b/repo_helper.yml
@@ -79,6 +79,7 @@ extra_sphinx_extensions:
 
 tox_unmanaged:
   - pytest
+  - testenv
 
 sphinx_conf_epilogue:
   - html_logo = "../sphinx_toolbox.png"
@@ -106,6 +107,7 @@ third_party_version_matrix:
     - 4.4
     - 4.5
     - 5.0
+    - 5.1
 #    - latest
 
 classifiers:

diff --git a/requirements.txt b/requirements.txt
@@ -4,7 +4,7 @@ autodocsumm>=0.2.0
 beautifulsoup4>=4.9.1
 cachecontrol[filecache]>=0.12.6
 dict2css>=0.2.3
-docutils<0.18,>=0.16
+docutils<0.19,>=0.16
 domdf-python-tools>=2.9.0
 html5lib>=1.1
 lockfile>=0.12.2

diff --git a/sphinx_toolbox/_data_documenter.py b/sphinx_toolbox/_data_documenter.py
@@ -34,9 +34,10 @@
 #
 
 # stdlib
-from typing import Any, get_type_hints
+from typing import Any, Optional, get_type_hints
 
 # 3rd party
+from docutils.statemachine import StringList
 from sphinx.ext.autodoc import (
 		SUPPRESS,
 		UNINITIALIZED_ATTR,
@@ -48,6 +49,9 @@
 from sphinx.util.inspect import object_description, safe_getattr
 from sphinx.util.typing import stringify as stringify_typehint
 
+# this package
+from sphinx_toolbox.more_autodoc import _documenter_add_content
+
 __all__ = ("DataDocumenter", )
 
 logger = logging.getLogger(__name__)
@@ -127,3 +131,10 @@ def get_real_modname(self) -> str:
 		"""
 
 		return self.get_attr(self.parent or self.object, "__module__", None) or self.modname
+
+	def add_content(self, more_content: Optional[StringList], no_docstring: bool = False) -> None:
+		"""
+		Add content from docstrings, attribute documentation and user.
+		"""
+
+		_documenter_add_content(self, more_content, no_docstring)
diff --git a/sphinx_toolbox/flake8.py b/sphinx_toolbox/flake8.py
@@ -62,6 +62,7 @@
 from typing import List, Sequence, Tuple
 
 # 3rd party
+import docutils
 import tabulate
 from docutils import nodes
 from docutils.statemachine import StringList
@@ -125,6 +126,9 @@ def run(self) -> Sequence[nodes.Node]:  # type: ignore[override]
 		table_node = nodes.paragraph(rawsource=content)
 		self.state.nested_parse(view, self.content_offset, table_node)
 
+		if docutils.__version_info__ >= (0, 18):
+			table_node.children[0]["classes"] += ["colwidths-given"]  # type: ignore[index]
+
 		table_node_purger.add_node(self.env, table_node, targetnode, self.lineno)
 
 		return [table_node]

diff --git a/sphinx_toolbox/latex/__init__.py b/sphinx_toolbox/latex/__init__.py
@@ -550,7 +550,12 @@ def write(self, *ignored: Any) -> None:
 			with progress_message(__("processing %s") % targetname):
 				doctree = self.env.get_doctree(docname)
 				process_only_nodes(doctree, self.tags)
-				toctree = next(iter(doctree.traverse(addnodes.toctree)), None)
+
+				if hasattr(doctree, "findall"):
+					toctree = next(doctree.findall(addnodes.toctree), None)  # type: ignore[attr-defined]
+				else:
+					toctree = next(iter(doctree.traverse(addnodes.toctree)), None)
+
 				if toctree and toctree.get("maxdepth") > 0:
 					tocdepth = toctree.get("maxdepth")
 				else:

diff --git a/sphinx_toolbox/more_autodoc/__init__.py b/sphinx_toolbox/more_autodoc/__init__.py
@@ -57,10 +57,12 @@
 #
 
 # stdlib
-from typing import TYPE_CHECKING, Any, List, Tuple
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple
 
 # 3rd party
+from docutils.statemachine import StringList
 from sphinx.application import Sphinx
+from sphinx.ext.autodoc import Documenter
 
 # this package
 from sphinx_toolbox.utils import SphinxExtMetadata, metadata_add_version
@@ -76,6 +78,51 @@
 __all__ = ("setup", )
 
 
+def _documenter_add_content(
+		self: Documenter,
+		more_content: Optional[StringList],
+		no_docstring: bool = False,
+		) -> None:
+	"""
+	Add content from docstrings, attribute documentation and user.
+	"""
+
+	# set sourcename and add content from attribute documentation
+	sourcename = self.get_sourcename()
+	if self.analyzer:
+		attr_docs = self.analyzer.find_attr_docs()
+		if self.objpath:
+			key = ('.'.join(self.objpath[:-1]), self.objpath[-1])
+			if key in attr_docs:
+				no_docstring = True
+				# make a copy of docstring for attributes to avoid cache
+				# the change of autodoc-process-docstring event.
+				docstrings = [list(attr_docs[key])]
+
+				for i, line in enumerate(self.process_doc(docstrings)):
+					self.add_line(line, sourcename, i)
+
+	# add content from docstrings
+	if not no_docstring:
+		docstrings = self.get_doc() or []
+		if docstrings is None:
+			# Do not call autodoc-process-docstring on get_doc() returns None.
+			pass
+		else:
+			if not docstrings:
+				# append at least a dummy docstring, so that the event
+				# autodoc-process-docstring is fired and can add some
+				# content if desired
+				docstrings.append([])
+			for i, line in enumerate(self.process_doc(docstrings)):
+				self.add_line(line, sourcename, i)
+
+	# add additional content (e.g. from document), if present
+	if more_content:
+		for line, src in zip(more_content.data, more_content.items):
+			self.add_line(line, src[0], src[1])
+
+
 @metadata_add_version
 def setup(app: Sphinx) -> SphinxExtMetadata:
 	"""

diff --git a/sphinx_toolbox/more_autodoc/augment_defaults.py b/sphinx_toolbox/more_autodoc/augment_defaults.py
@@ -78,6 +78,7 @@
 
 # this package
 import sphinx_toolbox
+import sphinx_toolbox.more_autosummary
 from sphinx_toolbox.utils import Config, SphinxExtMetadata
 
 __all__ = ("process_documenter_options", "setup")
@@ -132,6 +133,7 @@ def setup(app: Sphinx) -> SphinxExtMetadata:
 
 	sphinx.ext.autodoc.directive.process_documenter_options = process_documenter_options  # type: ignore[assignment]
 	autodocsumm.process_documenter_options = process_documenter_options
+	sphinx_toolbox.more_autosummary.process_documenter_options = process_documenter_options  # type: ignore[assignment]
 
 	app.setup_extension("sphinx.ext.autodoc")
 

diff --git a/sphinx_toolbox/more_autodoc/autonamedtuple.py b/sphinx_toolbox/more_autodoc/autonamedtuple.py
@@ -128,15 +128,14 @@
 import re
 import sys
 import textwrap
-import warnings
 from textwrap import dedent
 from typing import Any, Dict, List, Optional, Tuple, Type, cast, get_type_hints
 
 # 3rd party
 from docutils import nodes
+from docutils.statemachine import StringList
 from sphinx import addnodes
 from sphinx.application import Sphinx
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.domains import ObjType
 from sphinx.domains.python import PyAttribute, PyClasslike, PythonDomain, PyXRefRole
 from sphinx.ext.autodoc import ClassDocumenter, Documenter, Options
@@ -146,7 +145,7 @@
 from sphinx.util.nodes import make_id
 
 # this package
-from sphinx_toolbox.more_autodoc import ObjectMembers
+from sphinx_toolbox.more_autodoc import ObjectMembers, _documenter_add_content
 from sphinx_toolbox.more_autodoc.typehints import format_annotation
 from sphinx_toolbox.utils import (
 		Param,
@@ -205,7 +204,7 @@ def can_document_member(
 
 		return is_namedtuple(member)
 
-	def add_content(self, more_content: Any, no_docstring: bool = True) -> None:
+	def add_content(self, more_content: Optional[StringList], no_docstring: bool = True) -> None:
 		r"""
 		Add extra content (from docstrings, attribute docs etc.),
 		but not the :class:`typing.NamedTuple`\'s docstring.
@@ -214,11 +213,7 @@ def add_content(self, more_content: Any, no_docstring: bool = True) -> None:
 		:param no_docstring:
 		"""  # noqa: D400
 
-		with warnings.catch_warnings():
-			# TODO: work out what to do about this
-			warnings.simplefilter("ignore", RemovedInSphinx50Warning)
-
-			Documenter.add_content(self, more_content, True)
+		_documenter_add_content(self, more_content, True)
 
 		# set sourcename and add content from attribute documentation
 		sourcename = self.get_sourcename()

diff --git a/sphinx_toolbox/more_autodoc/autoprotocol.py b/sphinx_toolbox/more_autodoc/autoprotocol.py
@@ -130,9 +130,10 @@
 
 # stdlib
 import sys
-from typing import Any, Callable, Dict, List, Tuple
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
 # 3rd party
+from docutils.statemachine import StringList
 from sphinx.application import Sphinx
 from sphinx.domains import ObjType
 from sphinx.domains.python import PyClasslike, PyXRefRole
@@ -149,7 +150,7 @@
 from sphinx.util.inspect import getdoc, safe_getattr
 
 # this package
-from sphinx_toolbox.more_autodoc import ObjectMembers
+from sphinx_toolbox.more_autodoc import ObjectMembers, _documenter_add_content
 from sphinx_toolbox.more_autodoc.generic_bases import _add_generic_bases
 from sphinx_toolbox.utils import (
 		SphinxExtMetadata,
@@ -265,15 +266,15 @@ def format_signature(self, **kwargs: Any) -> str:
 
 		return ''  # pragma: no cover
 
-	def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
+	def add_content(self, more_content: Optional[StringList], no_docstring: bool = False) -> None:
 		"""
 		Add the autodocumenter content.
 
 		:param more_content:
 		:param no_docstring:
 		"""
 
-		super().add_content(more_content=more_content, no_docstring=no_docstring)
+		_documenter_add_content(self, more_content, no_docstring)
 
 		sourcename = self.get_sourcename()
 

diff --git a/sphinx_toolbox/more_autodoc/overloads.py b/sphinx_toolbox/more_autodoc/overloads.py
@@ -106,6 +106,7 @@
 from sphinx.util.inspect import evaluate_signature, safe_getattr, stringify_signature
 
 # this package
+from sphinx_toolbox.more_autodoc import _documenter_add_content
 from sphinx_toolbox.more_autodoc.typehints import _resolve_forwardref, default_preprocessors, format_annotation
 from sphinx_toolbox.utils import SphinxExtMetadata, metadata_add_version
 
@@ -291,12 +292,12 @@ def process_docstring(
 
 			listener_id = self.env.app.connect("autodoc-process-docstring", process_docstring, priority=600)
 			try:
-				super().add_content(more_content, no_docstring)
+				_documenter_add_content(self, more_content, no_docstring)
 			finally:
 				self.env.app.disconnect(listener_id)
 
 		else:
-			super().add_content(more_content, no_docstring)
+			_documenter_add_content(self, more_content, no_docstring)
 
 
 class FunctionDocumenter(OverloadMixin, autodoc.FunctionDocumenter):