autodoc of invoke fails with newer versions of sphinx

[briggySmalls]

My builds have started to fail:

Running Sphinx v2.4.4

Exception occurred:
  File "/Users/sambriggs/.local/share/virtualenvs/cookiecutter-pypackage-oT8-zJK2/lib/python3.7/site-packages/sphinx/deprecation.py", line 49, in __getattr__
    return getattr(self._module, name)
AttributeError: module 'sphinx.ext.autodoc' has no attribute 'add_documenter'
The full traceback has been saved in /var/folders/vz/gcfll7gd04z1sbzr9kv2phn80000gn/T/sphinx-err-qijxis7s.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 <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

The traceback looks like:

# Sphinx version: 2.4.4
# Python version: 3.7.6 (CPython)
# Docutils version: 0.16 release
# Jinja2 version: 2.11.1
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "/Users/sambriggs/.local/share/virtualenvs/cookiecutter-pypackage-oT8-zJK2/lib/python3.7/site-packages/sphinx/cmd/build.py", line 275, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/Users/sambriggs/.local/share/virtualenvs/cookiecutter-pypackage-oT8-zJK2/lib/python3.7/site-packages/sphinx/application.py", line 245, in __init__
    self.setup_extension(extension)
  File "/Users/sambriggs/.local/share/virtualenvs/cookiecutter-pypackage-oT8-zJK2/lib/python3.7/site-packages/sphinx/application.py", line 397, in setup_extension
    self.registry.load_extension(self, extname)
  File "/Users/sambriggs/.local/share/virtualenvs/cookiecutter-pypackage-oT8-zJK2/lib/python3.7/site-packages/sphinx/registry.py", line 465, in load_extension
    metadata = setup(app)
  File "/Users/sambriggs/.local/share/virtualenvs/cookiecutter-pypackage-oT8-zJK2/lib/python3.7/site-packages/invocations/autodoc.py", line 90, in setup
    autodoc.add_documenter(TaskDocumenter)
  File "/Users/sambriggs/.local/share/virtualenvs/cookiecutter-pypackage-oT8-zJK2/lib/python3.7/site-packages/sphinx/deprecation.py", line 49, in __getattr__
    return getattr(self._module, name)
AttributeError: module 'sphinx.ext.autodoc' has no attribute 'add_documenter'

The offending line carries an explanation of why the extension is calling an internal API:

NOTE: sooo for now, since a bunch of our other shit breaks on Sphinx 1.7, we are just explicitly calling autodoc's add_documenter. Sadface.

But it looks like now is the time that it needs fixing!

https://github.com/pyinvoke/invocations/blob/b3fdef7e428dc8b410f49e8e00a25391fa600b5a/invocations/autodoc.py#L90

[kloczek]

Just tested 2.6.0 and looks like issue still is around ..

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v4.5.0

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 223, in __init__
    self.setup_extension(extension)
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 380, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/lib/python3.8/site-packages/sphinx/registry.py", line 438, in load_extension
    metadata = setup(app)
  File "/home/tkloczko/rpmbuild/BUILD/invocations-2.6.0/invocations/autodoc.py", line 90, in setup
    autodoc.add_documenter(TaskDocumenter)
AttributeError: module 'sphinx.ext.autodoc' has no attribute 'add_documenter'

Exception occurred:
  File "/home/tkloczko/rpmbuild/BUILD/invocations-2.6.0/invocations/autodoc.py", line 90, in setup
    autodoc.add_documenter(TaskDocumenter)
AttributeError: module 'sphinx.ext.autodoc' has no attribute 'add_documenter'
The full traceback has been saved in /tmp/sphinx-err-fq3a361m.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 <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

[anernest]

I'm getting a 'getargspec' error with Sphinx v5.0.0

Sphinx's deprecated list recommend pulling it from 'inspect', which in turn results in the 'add_documenter' error...

sphinx.util.inspect.getargspec() | 3.0 | 5.0 | inspect.getargspec() -- | -- | -- | --

`Running Sphinx v5.0.0

Extension error: Could not import extension invocations.autodoc (exception: cannot import name 'getargspec' from 'sphinx.util.inspect' (/home/anernest/Tier1Implementation/.venv/lib/python3.8/site-packages/sphinx/util/inspect.py)) make: *** [Makefile:28: html] Error 2`

[kasium]

I had a similar issue with invoke and sphinx and created https://github.com/SAP/invoke-plugin-for-sphinx to document invoke tasks properly. Maybe this finds it's way into invoke in the near future.

Disclaimer: I'm the author of invoke-plugin-for-sphinx

[kloczek]

Currently with sphinx 7.3.7 I have completely different fail

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v7.3.7
making output directory... done
loading intersphinx inventory from http://docs.python.org/objects.inv...
loading intersphinx inventory from /home/tkloczko/rpmbuild/BUILD/invocations-3.3.0/docs/../../invoke/sites/docs/_build/objects.inv...
WARNING: failed to reach any of the inventories with the following issues:
intersphinx inventory '/home/tkloczko/rpmbuild/BUILD/invocations-3.3.0/docs/../../invoke/sites/docs/_build/objects.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/home/tkloczko/rpmbuild/BUILD/invocations-3.3.0/docs/../../invoke/sites/docs/_build/objects.inv'
intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [man]: all manpages
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [ 11%] api/autodoc
reading sources... [ 22%] api/ci
reading sources... [ 33%] api/console
reading sources... [ 44%] api/docs
reading sources... [ 56%] api/environment
reading sources... [ 67%] api/packaging
reading sources... [ 78%] api/pytest
reading sources... [ 89%] changelog
reading sources... [100%] index

WARNING: autodoc: failed to import module 'packaging.release' from module 'invocations'; the following exception was raised:
No module named 'invoke.vendor'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... invocations.1 { changelog api/autodoc api/ci api/console api/docs api/environment api/packaging api/pytest } /home/tkloczko/rpmbuild/BUILD/invocations-3.3.0/docs/changelog.rst:5: WARNING: unknown node type: <release 3.3.0>
failed

Traceback (most recent call last):
  File "/usr/lib/python3.10/site-packages/sphinx/cmd/build.py", line 337, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.10/site-packages/sphinx/application.py", line 351, in build
    self.builder.build_update()
  File "/usr/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 290, in build_update
    self.build(['__all__'], to_build)
  File "/usr/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 362, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/lib/python3.10/site-packages/sphinx/util/display.py", line 93, in wrapper
    return f(*args, **kwargs)
  File "/usr/lib/python3.10/site-packages/sphinx/builders/manpage.py", line 105, in write
    docwriter.write(largetree, destination)
  File "/usr/lib/python3.10/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/usr/lib/python3.10/site-packages/sphinx/writers/manpage.py", line 37, in translate
    self.document.walkabout(visitor)
  File "/usr/lib/python3.10/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.10/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  File "/usr/lib/python3.10/site-packages/docutils/nodes.py", line 186, in walkabout
    if child.walkabout(visitor):
  [Previous line repeated 6 more times]
  File "/usr/lib/python3.10/site-packages/docutils/nodes.py", line 199, in walkabout
    visitor.dispatch_departure(self)
  File "/usr/lib/python3.10/site-packages/sphinx/util/docutils.py", line 588, in dispatch_departure
    super().dispatch_departure(node)
  File "/usr/lib/python3.10/site-packages/docutils/nodes.py", line 2019, in dispatch_departure
    return method(node)
  File "/usr/lib/python3.10/site-packages/docutils/nodes.py", line 2041, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.manpage.ManualPageTranslator'> departing unknown node type: Release

Exception occurred:
  File "/usr/lib/python3.10/site-packages/docutils/nodes.py", line 2041, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'sphinx.writers.manpage.ManualPageTranslator'> departing unknown node type: Release
The full traceback has been saved in /tmp/sphinx-err-au6c9fhi.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 <https://github.com/sphinx-doc/sphinx/issues>. Thanks!