sphinxext: fix warning message for detailed list

Fix the way the warning for undocumented modules in a detail list is
produced. The new importlib.metadata.EntryPoint type is derived from
namedtuple so using string interpolation means the multi-part tuple
causes an error. Take the opportunity to include a more detailed
message.

Change-Id: I02223a982258a1bf8fc28fa91c7c090c7ac3554e
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

releasenotes/notes/module-name-property-d3b2d092259dadec.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Add a `module_name` property to the `Extension` class to make it easier
+    for consumers to determine where the plugin is being loaded from.

stevedore/extension.py

@@ -47,6 +47,17 @@ class Extension(object):
         self.plugin = plugin
         self.obj = obj
 
+    @property
+    def module_name(self):
+        """The name of the module from which the entry point is loaded.
+
+        :return: A string in 'dotted.module' format.
+        """
+        # NOTE: importlib_metadata from PyPI includes this but the
+        # Python 3.8 standard library does not.
+        match = self.entry_point.pattern.match(self.entry_point.value)
+        return match.group('module')
+
     @property
     def entry_point_target(self):
         """The module and attribute referenced by this extension's entry_point.

stevedore/sphinxext.py

@@ -34,29 +34,32 @@ def _simple_list(mgr):
         doc = _get_docstring(ext.plugin) or '\n'
         summary = doc.splitlines()[0].strip()
         yield('* %s -- %s' % (ext.name, summary),
-              ext.entry_point.module)
+              ext.module_name)
 
 
 def _detailed_list(mgr, over='', under='-', titlecase=False):
     for name in sorted(mgr.names()):
         ext = mgr[name]
         if over:
-            yield (over * len(ext.name), ext.entry_point.module)
+            yield (over * len(ext.name), ext.module_name)
         if titlecase:
-            yield (ext.name.title(), ext.entry_point.module)
+            yield (ext.name.title(), ext.module_name)
         else:
-            yield (ext.name, ext.entry_point.module)
+            yield (ext.name, ext.module_name)
         if under:
-            yield (under * len(ext.name), ext.entry_point.module)
-        yield ('\n', ext.entry_point.module)
+            yield (under * len(ext.name), ext.module_name)
+        yield ('\n', ext.module_name)
         doc = _get_docstring(ext.plugin)
         if doc:
-            yield (doc, ext.entry_point.module)
+            yield (doc, ext.module_name)
         else:
-            yield ('.. warning:: No documentation found in %s'
-                   % ext.entry_point,
-                   ext.entry_point.module)
-        yield ('\n', ext.entry_point.module)
+            yield (
+                '.. warning:: No documentation found for {} in {}'.format(
+                    ext.name, ext.entry_point_target,
+                ),
+                ext.module_name,
+            )
+        yield ('\n', ext.module_name)
 
 
 class ListPluginsDirective(rst.Directive):

stevedore/tests/test_sphinxext.py

@@ -12,8 +12,6 @@
 """Tests for the sphinx extension
 """
 
-from unittest import mock
-
 try:
     # For python 3.8 and later
     import importlib.metadata as importlib_metadata
@@ -31,10 +29,9 @@ def _make_ext(name, docstring):
         pass
 
     inner.__doc__ = docstring
-    m1 = mock.Mock(spec=importlib_metadata.EntryPoint)
-    m1.module = '%s_module' % name
-    s = mock.Mock(return_value='ENTRY_POINT(%s)' % name)
-    m1.__str__ = s
+    m1 = importlib_metadata.EntryPoint(
+        name, '{}_module:{}'.format(name, name), 'group',
+    )
     return extension.Extension(name, m1, inner, None)
 
 
@@ -116,7 +113,8 @@ class TestSphinxExt(utils.TestCase):
                 ('nodoc', 'nodoc_module'),
                 ('-----', 'nodoc_module'),
                 ('\n', 'nodoc_module'),
-                ('.. warning:: No documentation found in ENTRY_POINT(nodoc)',
+                (('.. warning:: No documentation found for '
+                 'nodoc in nodoc_module:nodoc'),
                  'nodoc_module'),
                 ('\n', 'nodoc_module'),
             ],