builds fail with a KeyError 'refexplicit' when using sphinx 3.0.0

[rocco8773]

When trying to fix our documentation builds on https://github.com/PlasmaPy/PlasmaPy/pull/780 I discovered there's an incompatibility with sphinx v3.0.0 (see error log below). When I freeze sphinx to v2.4.4 or exclude sphinx_automodapi.smart_resolver, then the error resolves. I think this is also related to #98 and looks very similar to https://github.com/sphinx-doc/sphinx/issues/3350, which was resolved like this https://github.com/sphinx-doc/sphinx/commit/1498897278fdc682025e0169b818429f112996c3.

Error log

# Sphinx version: 3.0.0
# Python version: 3.7.6 (CPython)
# Docutils version: 0.16 release
# Jinja2 version: 2.10.3
# Last messages:
#   writing output... [ 22%] api/plasmapy.formulary.collisions.impact_parameter
#   writing output... [ 23%] api/plasmapy.formulary.collisions.impact_parameter_perp
#   writing output... [ 23%] api/plasmapy.formulary.collisions.mean_free_path
#   writing output... [ 24%] api/plasmapy.formulary.collisions.mobility
#   writing output... [ 24%] api/plasmapy.formulary.dielectric.cold_plasma_permittivity_LRP
#   writing output... [ 25%] api/plasmapy.formulary.dielectric.cold_plasma_permittivity_SDP
#   writing output... [ 25%] api/plasmapy.formulary.dielectric.permittivity_1D_Maxwellian
#   writing output... [ 26%] api/plasmapy.formulary.dimensionless.beta
#   writing output... [ 26%] api/plasmapy.formulary.dimensionless.quantum_theta
#   writing output... [ 27%] api/plasmapy.formulary.dispersionfunction.plasma_dispersion_func
# Loaded extensions:
#   sphinx.ext.mathjax (3.0.0) from /.../site-packages/sphinx/ext/mathjax.py
#   sphinxcontrib.applehelp (1.0.1) from /.../site-packages/sphinxcontrib/applehelp/__init__.py
#   sphinxcontrib.devhelp (1.0.1) from /.../site-packages/sphinxcontrib/devhelp/__init__.py
#   sphinxcontrib.htmlhelp (1.0.2) from /.../site-packages/sphinxcontrib/htmlhelp/__init__.py
#   sphinxcontrib.serializinghtml (1.1.3) from /.../site-packages/sphinxcontrib/serializinghtml/__init__.py
#   sphinxcontrib.qthelp (1.0.2) from /.../site-packages/sphinxcontrib/qthelp/__init__.py
#   alabaster (0.7.12) from /.../site-packages/alabaster/__init__.py
#   sphinx.ext.autodoc.type_comment (3.0.0) from /.../site-packages/sphinx/ext/autodoc/type_comment.py
#   sphinx.ext.autodoc (3.0.0) from /.../site-packages/sphinx/ext/autodoc/__init__.py
#   sphinx.ext.intersphinx (3.0.0) from /.../site-packages/sphinx/ext/intersphinx.py
#   sphinx.ext.graphviz (3.0.0) from /.../site-packages/sphinx/ext/graphviz.py
#   sphinx.ext.napoleon (3.0.0) from /.../site-packages/sphinx/ext/napoleon/__init__.py
#   sphinx.ext.autosummary (3.0.0) from /.../site-packages/sphinx/ext/autosummary/__init__.py
#   sphinx_automodapi.autodoc_enhancements (unknown version) from /.../site-packages/sphinx_automodapi/autodoc_enhancements.py
#   sphinx.ext.inheritance_diagram (3.0.0) from /.../site-packages/sphinx/ext/inheritance_diagram.py
#   sphinx_automodapi.automodsumm (unknown version) from /.../site-packages/sphinx_automodapi/automodsumm.py
#   sphinx_automodapi.automodapi (unknown version) from /.../site-packages/sphinx_automodapi/automodapi.py
#   sphinx_automodapi.smart_resolver (unknown version) from /.../site-packages/sphinx_automodapi/smart_resolver.py
#   sphinx_gallery.gen_gallery (0.6.1) from /.../site-packages/sphinx_gallery/gen_gallery.py
Traceback (most recent call last):
  File "/.../site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/.../site-packages/sphinx/application.py", line 348, in build
    self.builder.build_update()
  File "/.../site-packages/sphinx/builders/__init__.py", line 299, in build_update
    len(to_build))
  File "/.../site-packages/sphinx/builders/__init__.py", line 361, in build
    self.write(docnames, list(updated_docnames), method)
  File "/.../site-packages/sphinx/builders/__init__.py", line 535, in write
    self._write_serial(sorted(docnames))
  File "/.../site-packages/sphinx/builders/__init__.py", line 542, in _write_serial
    doctree = self.env.get_and_resolve_doctree(docname, self)
  File "/.../site-packages/sphinx/environment/__init__.py", line 538, in get_and_resolve_doctree
    self.apply_post_transforms(doctree, docname)
  File "/.../site-packages/sphinx/environment/__init__.py", line 584, in apply_post_transforms
    transformer.apply_transforms()
  File "/.../site-packages/sphinx/transforms/__init__.py", line 86, in apply_transforms
    super().apply_transforms()
  File "/.../site-packages/docutils/transforms/__init__.py", line 171, in apply_transforms
    transform.apply(**kwargs)
  File "/.../site-packages/sphinx/transforms/post_transforms/__init__.py", line 44, in apply
    self.run(**kwargs)
  File "/.../site-packages/sphinx/transforms/post_transforms/__init__.py", line 95, in run
    node, contnode)
  File "/.../site-packages/sphinx/application.py", line 454, in emit_firstresult
    return self.events.emit_firstresult(event, *args)
  File "/.../site-packages/sphinx/events.py", line 115, in emit_firstresult
    for result in self.emit(name, *args):
  File "/.../site-packages/sphinx/events.py", line 107, in emit
    results.append(listener.handler(self.app, *args))
  File "/.../site-packages/sphinx_automodapi/smart_resolver.py", line 78, in missing_reference_handler
    if not node['refexplicit'] and \
  File "/.../site-packages/docutils/nodes.py", line 625, in __getitem__
    return self.attributes[key]
KeyError: 'refexplicit'

[gruel]

I had the same problem and I found that the problem is coming because of some 'not so simple' typing e.g.:

def funct(n1: int, n2: str ) -> List[int, str]:

the solution I found is to use the extension typehints https://github.com/agronholm/sphinx-autodoc-typehints

[bsipocz]

would either of you interested in opening a PR with the fix?

I also vaguely recall the sunpy folks run into a sphinx issue, too with 3.0, maybe it was the same? cc @Cadair

[rocco8773]

@bsipocz My knowledge of sphinx-automodapi's inner workings is limited, but I can give it the old college try. If it's as simple as the example I linked, then it should be straight forward.

[astrofrog]

@rocco8773 - thanks!