BUG: Resolve .. include:: directive already in Doc.docstring

Otherwise `pdoc.html_helpers.extract_toc()` doesn't work.

Refs: eda27f3

pdoc/__init__.py

@@ -420,9 +420,14 @@ def __init__(self, name, module, obj, docstring=None):
         The raw python object.
         """
 
-        self.docstring = (docstring or inspect.getdoc(obj) or '').strip()
-        """
-        The cleaned docstring for this object.
+        docstring = (docstring or inspect.getdoc(obj) or '').strip()
+        if '.. include::' in docstring:
+            from pdoc.html_helpers import _ToMarkdown
+            docstring = _ToMarkdown.admonitions(docstring, self.module, ('include',))
+        self.docstring = docstring
+        """
+        The cleaned docstring for this object with any `.. include::`
+        directives resolved (i.e. content included).
         """
 
         self.inherits = None  # type: Union[Class, Function, Variable]

pdoc/html_helpers.py

@@ -187,9 +187,12 @@ def google(text,
         return _googledoc_sections(text)
 
     @staticmethod
-    def _admonition(match, module=None):
+    def _admonition(match, module=None, limit_types=None):
         indent, type, value, text = match.groups()
 
+        if limit_types and type not in limit_types:
+            return match.group(0)
+
         if type == 'include' and module:
             try:
                 return _ToMarkdown._include_file(indent, value,
@@ -223,17 +226,20 @@ def _admonition(match, module=None):
         return '{}!!! {} "{}"\n{}\n'.format(indent, type, title, text)
 
     @staticmethod
-    def admonitions(text, module):
+    def admonitions(text, module, limit_types=None):
         """
         Process reStructuredText's block directives such as
         `.. warning::`, `.. deprecated::`, `.. versionadded::`, etc.
         and turn them into Python-M>arkdown admonitions.
 
+        `limit_types` is optionally a set of directives to limit processing to.
+
         See: https://python-markdown.github.io/extensions/admonition/
         """
         substitute = partial(re.compile(r'^(?P<indent> *)\.\. ?(\w+)::(?: *(.*))?'
                                         r'((?:\n(?:(?P=indent) +.*| *$))*)', re.MULTILINE).sub,
-                             partial(_ToMarkdown._admonition, module=module))
+                             partial(_ToMarkdown._admonition, module=module,
+                                     limit_types=limit_types))
         # Apply twice for nested (e.g. image inside warning)
         return substitute(substitute(text))
 

pdoc/test/__init__.py

@@ -961,6 +961,11 @@ def test_reST_include(self):
         html = to_html(text, module=mod)
         self.assertEqual(html, expected)
 
+        # Ensure includes are resolved within docstrings already,
+        # e.g. for `pdoc.html_helpers.extract_toc()` to work
+        self.assertIn('Command-line interface',
+                      pdoc.Module(pdoc.import_module(pdoc)).docstring)
+
     def test_urls(self):
         text = """Beautiful Soup
 http://www.foo.bar