search

zopefoundation / ZODB

Python object-oriented database
https://zodb-docs.readthedocs.io/
Other
683 stars 92 forks source link

5.7.0: documentation build fails with sphinx 5.x #363

Closed kloczek closed 2 years ago

kloczek commented 2 years ago

Looks like it is not possible to generate documentation using sphinx 5.x

```console + /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man Running Sphinx v5.0.1 making output directory... done loading intersphinx inventory from https://docs.python.org/3/objects.inv... loading intersphinx inventory from https://persistent.readthedocs.io/en/latest/objects.inv... loading intersphinx inventory from https://docs.pylonsproject.org/projects/zodburi/en/latest/objects.inv... loading intersphinx inventory from https://btrees.readthedocs.io/en/latest/objects.inv... building [mo]: targets for 0 po files that are out of date building [man]: all manpages updating environment: [new config] 33 added, 0 changed, 0 removed /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/guide/writing-persistent-objects.rst:703: WARNING: Footnote [#] is not referenced. /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". WARNING: missing attribute setUser in interface transaction.interfaces.ITransaction Traceback (most recent call last): File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main app.build(args.force_all, filenames) File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 329, in build self.builder.build_update() File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 285, in build_update self.build(['__all__'], to_build) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 302, in build updated_docnames = set(self.read()) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 409, in read self._read_serial(docnames) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 430, in _read_serial self.read_doc(docname) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 483, in read_doc publisher.publish() File "/usr/lib/python3.8/site-packages/docutils/core.py", line 217, in publish self.document = self.reader.read(self.source, self.parser, File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 103, in read self.parse() File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 78, in parse self.parser.parse(self.input, document) File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 78, in parse self.statemachine.run(inputlines, document, inliner=self.inliner) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 170, in run results = StateMachineWS.run(self, input_lines, input_offset, File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 3008, in text self.section(title.lstrip(), source, style, lineno + 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2769, in underline self.section(title, source, style, lineno - 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2342, in explicit_markup nodelist, blank_finish = self.explicit_construct(match) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_construct return method(self, expmatch) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2096, in directive return self.run_directive( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2146, in run_directive result = directive_instance.run() File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 148, in run documenter.generate(more_content=self.content) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1788, in generate return super().generate(more_content=more_content, File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 955, in generate self.document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1779, in document_members super().document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 831, in document_members documenter.generate( File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 206, in generate super().generate(*v, **kw) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 952, in generate self.add_content(more_content) File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 219, in add_content super().add_content(more_content, no_docstring) TypeError: add_content() takes 2 positional arguments but 3 were given Exception occurred: File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 219, in add_content super().add_content(more_content, no_docstring) TypeError: add_content() takes 2 positional arguments but 3 were given The full traceback has been saved in /tmp/sphinx-err-qtkx48l3.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at . Thanks! ``` ```console [tkloczko@devel-g2v SPECS]$ cat /tmp/sphinx-err-qtkx48l3.log # Sphinx version: 5.0.1 # Python version: 3.8.13 (CPython) # Docutils version: 0.17.1 release # Jinja2 version: 3.1.1 # Last messages: # reading sources... [ 63%] guide/install-and-run # reading sources... [ 66%] guide/transactions-and-threading # reading sources... [ 69%] guide/writing-persistent-objects # reading sources... [ 72%] historical_connections # reading sources... [ 75%] index # reading sources... [ 78%] introduction # reading sources... [ 81%] persistentclass # reading sources... [ 84%] reference/index # reading sources... [ 87%] reference/storages # reading sources... [ 90%] reference/transaction # Loaded extensions: # sphinx.ext.mathjax (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/mathjax.py # sphinxcontrib.applehelp (1.0.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/applehelp/__init__.py # sphinxcontrib.devhelp (1.0.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/devhelp/__init__.py # sphinxcontrib.htmlhelp (2.0.0) from /usr/lib/python3.8/site-packages/sphinxcontrib/htmlhelp/__init__.py # sphinxcontrib.serializinghtml (1.1.5) from /usr/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py # sphinxcontrib.qthelp (1.0.3) from /usr/lib/python3.8/site-packages/sphinxcontrib/qthelp/__init__.py # alabaster (0.7.12) from /usr/lib/python3.8/site-packages/alabaster/__init__.py # sphinx.ext.autodoc.preserve_defaults (1.0) from /usr/lib/python3.8/site-packages/sphinx/ext/autodoc/preserve_defaults.py # sphinx.ext.autodoc.type_comment (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/autodoc/type_comment.py # sphinx.ext.autodoc (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py # sphinx.ext.doctest (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/doctest.py # sphinx.ext.intersphinx (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/intersphinx.py # sphinx.ext.viewcode (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/viewcode.py # sphinxcontrib.zopeext.autointerface (0.3.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py # j1m.sphinxautozconfig (unknown version) from /usr/lib/python3.8/site-packages/j1m/sphinxautozconfig.py Traceback (most recent call last): File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main app.build(args.force_all, filenames) File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 329, in build self.builder.build_update() File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 285, in build_update self.build(['__all__'], to_build) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 302, in build updated_docnames = set(self.read()) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 409, in read self._read_serial(docnames) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 430, in _read_serial self.read_doc(docname) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 483, in read_doc publisher.publish() File "/usr/lib/python3.8/site-packages/docutils/core.py", line 217, in publish self.document = self.reader.read(self.source, self.parser, File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 103, in read self.parse() File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 78, in parse self.parser.parse(self.input, document) File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 78, in parse self.statemachine.run(inputlines, document, inliner=self.inliner) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 170, in run results = StateMachineWS.run(self, input_lines, input_offset, File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 3008, in text self.section(title.lstrip(), source, style, lineno + 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2769, in underline self.section(title, source, style, lineno - 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2342, in explicit_markup nodelist, blank_finish = self.explicit_construct(match) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_construct return method(self, expmatch) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2096, in directive return self.run_directive( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2146, in run_directive result = directive_instance.run() File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 148, in run documenter.generate(more_content=self.content) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1788, in generate return super().generate(more_content=more_content, File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 955, in generate self.document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1779, in document_members super().document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 831, in document_members documenter.generate( File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 206, in generate super().generate(*v, **kw) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 952, in generate self.add_content(more_content) File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 219, in add_content super().add_content(more_content, no_docstring) TypeError: add_content() takes 2 positional arguments but 3 were given ```
kloczek commented 2 years ago

I forgot to mention that to use straight sphinx-build commend is necessatchy to use patch like below:

--- a/docs/conf.py~     2022-03-17 09:29:00.000000000 +0000
+++ b/docs/conf.py      2022-06-15 16:44:10.255216368 +0000
@@ -16,16 +16,15 @@

 import sys
 import os
-import pkg_resources
-import datetime
-
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.

 sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../src"))

+import pkg_resources
+import datetime

 # General configuration
 # ---------------------

Also ZODB uses pkg_resources so it would be good to migtate to importlib-metadata https://github.com/pypa/setuptools/issues/3279

kloczek commented 2 years ago

Call trace poited on j1m-sphinxautozconfig (this module seems is not maintained since 2016) however after remove that module

--- a/docs/conf.py~     2022-06-15 18:44:34.000000000 +0000
+++ b/docs/conf.py      2022-06-15 18:48:40.761196441 +0000
@@ -39,7 +39,6 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinxcontrib.zopeext.autointerface',
-    'j1m.sphinxautozconfig',
 ]

 # Add any paths that contain templates here, relative to this directory.

sphinx still fails

```console + /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man Running Sphinx v5.0.1 making output directory... done loading intersphinx inventory from https://docs.python.org/3/objects.inv... loading intersphinx inventory from https://persistent.readthedocs.io/en/latest/objects.inv... loading intersphinx inventory from https://docs.pylonsproject.org/projects/zodburi/en/latest/objects.inv... loading intersphinx inventory from https://btrees.readthedocs.io/en/latest/objects.inv... building [mo]: targets for 0 po files that are out of date building [man]: all manpages updating environment: [new config] 33 added, 0 changed, 0 removed /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/guide/writing-persistent-objects.rst:703: WARNING: Footnote [#] is not referenced. /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "documentation". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/index.rst:3: WARNING: Duplicate explicit target name: "repository". /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/reference/storages.rst:84: ERROR: Unknown directive type "zconfigsectionkeys". .. zconfigsectionkeys:: ZODB component.xml filestorage /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/reference/storages.rst:104: ERROR: Unknown directive type "zconfigsectionkeys". .. zconfigsectionkeys:: ZODB component.xml mappingstorage /home/tkloczko/rpmbuild/BUILD/ZODB-5.7.0/docs/reference/storages.rst:143: ERROR: Unknown directive type "zconfigsectionkeys". .. zconfigsectionkeys:: ZODB component.xml demostorage WARNING: missing attribute setUser in interface transaction.interfaces.ITransaction Traceback (most recent call last): File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main app.build(args.force_all, filenames) File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 329, in build self.builder.build_update() File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 285, in build_update self.build(['__all__'], to_build) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 302, in build updated_docnames = set(self.read()) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 409, in read self._read_serial(docnames) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 430, in _read_serial self.read_doc(docname) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 483, in read_doc publisher.publish() File "/usr/lib/python3.8/site-packages/docutils/core.py", line 217, in publish self.document = self.reader.read(self.source, self.parser, File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 103, in read self.parse() File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 78, in parse self.parser.parse(self.input, document) File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 78, in parse self.statemachine.run(inputlines, document, inliner=self.inliner) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 170, in run results = StateMachineWS.run(self, input_lines, input_offset, File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 3008, in text self.section(title.lstrip(), source, style, lineno + 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2769, in underline self.section(title, source, style, lineno - 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2342, in explicit_markup nodelist, blank_finish = self.explicit_construct(match) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_construct return method(self, expmatch) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2096, in directive return self.run_directive( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2146, in run_directive result = directive_instance.run() File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 148, in run documenter.generate(more_content=self.content) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1788, in generate return super().generate(more_content=more_content, File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 955, in generate self.document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1779, in document_members super().document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 831, in document_members documenter.generate( File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 206, in generate super().generate(*v, **kw) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 952, in generate self.add_content(more_content) File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 219, in add_content super().add_content(more_content, no_docstring) TypeError: add_content() takes 2 positional arguments but 3 were given Exception occurred: File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 219, in add_content super().add_content(more_content, no_docstring) TypeError: add_content() takes 2 positional arguments but 3 were given The full traceback has been saved in /tmp/sphinx-err-4gyqokk6.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at . Thanks! ``` ```console [tkloczko@devel-g2v SOURCES]$ cat /tmp/sphinx-err-4gyqokk6.log # Sphinx version: 5.0.1 # Python version: 3.8.13 (CPython) # Docutils version: 0.17.1 release # Jinja2 version: 3.1.1 # Last messages: # reading sources... [ 63%] guide/install-and-run # reading sources... [ 66%] guide/transactions-and-threading # reading sources... [ 69%] guide/writing-persistent-objects # reading sources... [ 72%] historical_connections # reading sources... [ 75%] index # reading sources... [ 78%] introduction # reading sources... [ 81%] persistentclass # reading sources... [ 84%] reference/index # reading sources... [ 87%] reference/storages # reading sources... [ 90%] reference/transaction # Loaded extensions: # sphinx.ext.mathjax (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/mathjax.py # sphinxcontrib.applehelp (1.0.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/applehelp/__init__.py # sphinxcontrib.devhelp (1.0.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/devhelp/__init__.py # sphinxcontrib.htmlhelp (2.0.0) from /usr/lib/python3.8/site-packages/sphinxcontrib/htmlhelp/__init__.py # sphinxcontrib.serializinghtml (1.1.5) from /usr/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py # sphinxcontrib.qthelp (1.0.3) from /usr/lib/python3.8/site-packages/sphinxcontrib/qthelp/__init__.py # alabaster (0.7.12) from /usr/lib/python3.8/site-packages/alabaster/__init__.py # sphinx.ext.autodoc.preserve_defaults (1.0) from /usr/lib/python3.8/site-packages/sphinx/ext/autodoc/preserve_defaults.py # sphinx.ext.autodoc.type_comment (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/autodoc/type_comment.py # sphinx.ext.autodoc (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py # sphinx.ext.doctest (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/doctest.py # sphinx.ext.intersphinx (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/intersphinx.py # sphinx.ext.viewcode (5.0.1) from /usr/lib/python3.8/site-packages/sphinx/ext/viewcode.py # sphinxcontrib.zopeext.autointerface (0.3.2) from /usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py Traceback (most recent call last): File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main app.build(args.force_all, filenames) File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 329, in build self.builder.build_update() File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 285, in build_update self.build(['__all__'], to_build) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 302, in build updated_docnames = set(self.read()) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 409, in read self._read_serial(docnames) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 430, in _read_serial self.read_doc(docname) File "/usr/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 483, in read_doc publisher.publish() File "/usr/lib/python3.8/site-packages/docutils/core.py", line 217, in publish self.document = self.reader.read(self.source, self.parser, File "/usr/lib/python3.8/site-packages/sphinx/io.py", line 103, in read self.parse() File "/usr/lib/python3.8/site-packages/docutils/readers/__init__.py", line 78, in parse self.parser.parse(self.input, document) File "/usr/lib/python3.8/site-packages/sphinx/parsers.py", line 78, in parse self.statemachine.run(inputlines, document, inliner=self.inliner) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 170, in run results = StateMachineWS.run(self, input_lines, input_offset, File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 3008, in text self.section(title.lstrip(), source, style, lineno + 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2769, in underline self.section(title, source, style, lineno - 1, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 327, in section self.new_subsection(title, lineno, messages) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection newabsoffset = self.nested_parse( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse state_machine.run(block, input_offset, memo=self.memo, File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 196, in run results = StateMachineWS.run(self, input_lines, input_offset) File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 239, in run context, next_state, result = self.check_line( File "/usr/lib/python3.8/site-packages/docutils/statemachine.py", line 451, in check_line return method(match, context, next_state) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2342, in explicit_markup nodelist, blank_finish = self.explicit_construct(match) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_construct return method(self, expmatch) File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2096, in directive return self.run_directive( File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2146, in run_directive result = directive_instance.run() File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/directive.py", line 148, in run documenter.generate(more_content=self.content) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1788, in generate return super().generate(more_content=more_content, File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 955, in generate self.document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 1779, in document_members super().document_members(all_members) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 831, in document_members documenter.generate( File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 206, in generate super().generate(*v, **kw) File "/usr/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py", line 952, in generate self.add_content(more_content) File "/usr/lib/python3.8/site-packages/sphinxcontrib/zopeext/autointerface.py", line 219, in add_content super().add_content(more_content, no_docstring) TypeError: add_content() takes 2 positional arguments but 3 were given ```

This time call trace points on sphinxcontrib.zopeext.autointerface. Maybe it would b better switch to regular repoze-sphinx-autointerface or reguler sphinx-autoapi? 🤔

jamesjer commented 2 years ago

Fedora has upgraded to sphinx 5.x in Rawhide, so the ZODB package is currently failing during the documentation building step. We would love to see a fix for this issue so that we can keep building the documentation.

kloczek commented 2 years ago

Fedora has upgraded to sphinx 5.x in Rawhide, so the ZODB package is currently failing during the documentation building step. We would love to see a fix for this issue so that we can keep building the documentation.

Fedora is producing html so my patch may be not enough for you (remove failing extension has no significant impact in case of roff output). Nevertheless this issue is related to usefailing sphinx extension.

icemac commented 2 years ago

The way to build the documentation for this project is to call:

tox -edocs

This runs successfully as shown by GitHub Actions. There are no guaranties that it is successful in any other way.

It currently uses Sphinx v4.5.0. The reason behind is that the sphinxcontrib-zopeext does not yet support Sphinx 5.x, see https://github.com/sphinx-contrib/zopeext/blob/b749d0023f4fb8b8eea3a8f3216f63397c6272de/pyproject.toml#L17

See https://github.com/sphinx-contrib/zopeext/issues/7 as the issue which has to be solved beforehand.

kloczek commented 2 years ago

Your tox target generates html. I need roff output (man page). Did you try to generated man page before writing that I should use tox?

icemac commented 2 years ago

@kloczek Thank you for the clarification what you need and what you want to achieve. It was not clear to me from the previous entries, sorry.

My comment about tox is still valid though: It installs the dependencies in the correct versions. We could change the tox configuration file, so you could add additional parameters to the sphinx-build call via the tox call on the command line to create the output format you need. – Would this help you?

kloczek commented 2 years ago

@kloczek Thank you for the clarification what you need and what you want to achieve. It was not clear to me from the previous entries, sorry.

First line of the log had command which I've been running 😋 

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man

My comment about tox is still valid though: It installs the dependencies in the correct versions

Really .. please have look one more time on the log whis aI've added to the ticket. None in that output pooints on missing bits in build env.

Here is list of modules installed in build env

```console Package Version --------------------------------- ----------------- alabaster 0.7.12 appdirs 1.4.4 astroid 2.12.5 attrs 22.1.0 Automat 20.2.0 Babel 2.10.2 backports.entry-points-selectable 1.1.1 Brlapi 0.8.3 BTrees 4.10.0 build 0.8.0 certifi 2021.10.8 cffi 1.15.1 charset-normalizer 2.1.0 click 8.1.3 click-default-group 1.2.2 codespell 2.1.0 constantly 15.1.0 coverage 6.4.4 cssselect 1.1.0 distlib 0.3.4 distro 1.7.0 docutils 0.18.1 dulwich 0.20.45 editables 0.3 extras 1.0.0 filelock 3.8.0 fixtures 4.0.0 flaky 3.7.0 freezegun 1.2.1 gpg 1.17.1-unknown hatch-fancy-pypi-readme 22.3.0 hatch-vcs 0.2.0 hatchling 1.8.1 hyperlink 21.0.0 idna 3.3 imagesize 1.4.1 importlib-metadata 4.12.0 importlib-resources 5.9.0 incremental 21.3.0 iniconfig 1.1.1 Jinja2 3.1.1 lazy-object-proxy 1.7.1 libcomps 0.1.18 louis 3.22.0 lxml 4.9.1 MarkupSafe 2.1.1 mock 4.0.3 mypy 0.971 mypy-extensions 0.4.3 numpy 1.23.1 packaging 21.3 pathspec 0.9.0 pbr 5.9.0 pep517 0.12.0 persistent 4.9.0 pip 22.2.1 pkgutil_resolve_name 1.3.10 platformdirs 2.5.2 pluggy 1.0.0 ply 3.11 purl 1.6 py 1.11.0 pycparser 2.21 pyenchant 3.2.2 Pygments 2.13.0 PyGObject 3.42.2 pyparsing 3.0.9 pyrsistent 0.18.1 pytest 7.1.2 pytest-freezegun 0.4.2 pytest-mock 3.8.2 pytest-randomly 3.12.0 pytest-timeout 2.1.0 python-dateutil 2.8.2 pytz 2022.1 PyYAML 6.0 reno 3.5.0 requests 2.28.1 requests-futures 1.0.0 rpm 4.17.0 scour 0.38.2 setuptools 65.3.0 setuptools-scm 7.0.5 six 1.16.0 snowballstemmer 2.2.0 Sphinx 5.1.1 sphinx-argparse 0.3.1 sphinx-autoapi 1.9.0 sphinx-autodoc-typehints 1.19.2 sphinx-rtd-theme 1.0.0 sphinxcontrib-applehelp 1.0.2.dev20220730 sphinxcontrib-devhelp 1.0.2.dev20220730 sphinxcontrib-htmlhelp 2.0.0 sphinxcontrib-jsmath 1.0.1.dev20220730 sphinxcontrib-qthelp 1.0.3.dev20220730 sphinxcontrib-serializinghtml 1.1.5 sphinxcontrib-spelling 7.6.0 sphinxcontrib-zopeext 0.3.2 testtools 2.5.0 tomli 2.0.1 towncrier 22.8.0 transaction 3.0.1 Twisted 22.4.0 typing_extensions 4.2.0 Unidecode 1.3.4 urllib3 1.26.12 webcolors 1.12 wheel 0.37.1 wrapt 1.14.0 zc.lockfile 2.0 ZConfig 3.6.0 zipp 3.8.1 zodbpickle 2.3 zope.event 4.5.0 zope.interface 5.4.0 zope.testing 4.10 ```
d-maurer commented 2 years ago

Tomasz Kłoczko wrote at 2022-8-31 04:35 -0700:

... Really .. please have look one more time on the log whis aI've added to the ticket.

... Package Version

... Sphinx 5.1.1 ...

You have been told (--> "https://github.com/zopefoundation/ZODB/issues/363#issuecomment-1232520739") that the documentation build currently cannot use Sphinx 5.x (together with good reasons).

kloczek commented 2 years ago

(--> "#363 (comment)") that the documentation build currently cannot use Sphinx 5.x (together with good reasons).

I want only to dsay that maybe it is time to choose other sphinx extension which is conuosly updated for sphinx 5.x? Sphinx no longer maintains 4.x 🤔 (and there isa no any plans to continue 4.x maintainance https://github.com/sphinx-doc/sphinx/branches)

icemac commented 2 years ago

@kloczek Thank you for sharing your environment. I don't know how you got there but it is invalid: sphinxcontrib-zopeext == 0.3.2 defines in its dependencies that it requires Sphinx = ">=3.4.2,<5.0.0", so pip should prevent installing it together with Sphinx >= 5.

Thank you for the hint to think about better dependencies. We'll postpone it until having an actual problem with Sphinx 4 due to limited time and manpower.

I am closing this issue as invalid as there is no actual error building the docs when using the expected tools. Feel free to open a new issue if you want to use tox to build the man-page format.