astropy · astrofrog · Apr 24, 2020 · Apr 19, 2020 · Apr 19, 2020 · Apr 20, 2020
diff --git a/azure-template.yml b/azure-template.yml
@@ -2,11 +2,11 @@ jobs:
 - job: ${{ format(parameters.name) }}
   pool:
     ${{ if eq(parameters.os, 'macosx') }}:
-      vmImage: macOS 10.13
+      vmImage: 'macOS-latest'
     ${{ if eq(parameters.os, 'linux') }}:
-      vmImage: Ubuntu 16.04
+      vmImage: 'ubuntu-latest'
     ${{ if eq(parameters.os, 'windows') }}:
-      vmImage: vs2017-win2016
+      vmImage: 'vs2017-win2016'
 
   steps:
 
@@ -40,7 +40,7 @@ jobs:
       versionSpec: '3.7'
       architecture: 'x64'
 
-  - script: pip install tox coverage
+  - script: pip install tox "coverage<5.0"
     displayName: Installing tox and coverage
 
   - script: tox

diff --git a/setup.cfg b/setup.cfg
@@ -28,7 +28,7 @@ test =
     pytest-cov
     cython
     codecov
-    coverage
+    coverage < 5.0
 
 [options.package_data]
 sphinx_automodapi = templates/*/*.rst

diff --git a/sphinx_automodapi/automodapi.py b/sphinx_automodapi/automodapi.py
@@ -166,7 +166,7 @@ class are included in the generated documentation. Defaults to ``False``.
 def automodapi_replace(sourcestr, app, dotoctree=True, docname=None,
                        warnings=True):
     """
-    Replaces `sourcestr`'s entries of ".. automdapi::" with the
+    Replaces `sourcestr`'s entries of ".. automodapi::" with the
     automodapi template form based on provided options.
 
     This is used with the sphinx event 'source-read' to replace

diff --git a/sphinx_automodapi/smart_resolver.py b/sphinx_automodapi/smart_resolver.py
@@ -34,20 +34,53 @@ def merge_mapping(app, env, docnames, env_other):
 
 
 def missing_reference_handler(app, env, node, contnode):
+    """
+    Handler to be connect to the sphinx 'missing-reference' event.  The handler a
+    resolves reference (node) and returns a new node when sphinx could not
+    originally resolve the reference.
+
+    see `missing-reference in sphinx documentation
+    <https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-missing-reference>`_
+
+    :param app: The Sphinx application object
+    :param env: The build environment (``app.builder.env`)
+    :param node: The ``pending_xref`` node to be resolved. Its attributes reftype,
+                 reftarget, modname and classname attributes determine the type and
+                 target of the reference.
+    :param contnode: The node that carries the text and formatting inside the
+                     future reference and should be a child of the returned
+                     reference node.
+    """
+    # a good example of how a missing reference handle works look to
+    #  https://github.com/sphinx-doc/sphinx/issues/1572#issuecomment-68590981
+    #
+    # Important attributes of the "node":
+    #
+    #      example role:  :ref:`title <target>`
+    #
+    #  'reftype'     - role name (in the example above 'ref' is the reftype)
+    #  'reftarget'   - target of the role, as given in the role content
+    #                  (in the example 'target' is the reftarget
+    #  'refexplicit' - the explicit title of the role
+    #                  (in the example 'title' is the refexplicit)
+    #  'refdoc'      - document in which the role appeared
+    #  'refdomain'   - domain of the role, in our case emtpy
 
     if not hasattr(env, 'class_name_mapping'):
         env.class_name_mapping = {}
     mapping = env.class_name_mapping
 
     reftype = node['reftype']
     reftarget = node['reftarget']
+    refexplicit = node.get('refexplicit')  # default: None
+    refdoc = node.get('refdoc', env.docname)
     if reftype in ('obj', 'class', 'exc', 'meth'):
-        reftarget = node['reftarget']
         suffix = ''
         if reftarget not in mapping:
             if '.' in reftarget:
                 front, suffix = reftarget.rsplit('.', 1)
             else:
+                front = None
                 suffix = reftarget
 
             if suffix.startswith('_') and not suffix.startswith('__'):
@@ -56,7 +89,7 @@ def missing_reference_handler(app, env, node, contnode):
                 # nitpick warning.
                 return node[0].deepcopy()
 
-            if reftype in ('obj', 'meth') and '.' in reftarget:
+            if reftype in ('obj', 'meth') and front is not None:
                 if front in mapping:
                     reftarget = front
                     suffix = '.' + suffix
@@ -73,10 +106,10 @@ def missing_reference_handler(app, env, node, contnode):
                 if (reftarget not in mapping and
                         prefix in inventory):
 
-                    if 'py:class' in inventory[prefix] and reftarget in inventory[prefix]['py:class']:
+                    if 'py:class' in inventory[prefix] and \
+                            reftarget in inventory[prefix]['py:class']:
                         newtarget = inventory[prefix]['py:class'][reftarget][2]
-                        if not node['refexplicit'] and \
-                                '~' not in node.rawsource:
+                        if not refexplicit and '~' not in node.rawsource:
                             contnode = literal(text=reftarget)
                         newnode = reference('', '', internal=True)
                         newnode['reftitle'] = reftarget
@@ -87,11 +120,10 @@ def missing_reference_handler(app, env, node, contnode):
 
         if reftarget in mapping:
             newtarget = mapping[reftarget] + suffix
-            if not node['refexplicit'] and '~' not in node.rawsource:
+            if not refexplicit and '~' not in node.rawsource:
                 contnode = literal(text=newtarget)
-            newnode = env.domains['py'].resolve_xref(
-                env, node['refdoc'], app.builder, 'class', newtarget,
-                node, contnode)
+            newnode = env.domains['py'].resolve_xref(env, refdoc, app.builder, 'class',
+                                                     newtarget, node, contnode)
             if newnode is not None:
                 newnode['reftitle'] = reftarget
             return newnode