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

Otherwise `pdoc.html_helpers.extract_toc()` doesn't work. Refs: eda27f3
pdoc3 · May 3, 2019 · 54fc6d04380ac3fbc36f951cb4842b2903ed53be · 54fc6d0
1 parent 05f8378
commit 54fc6d04380ac3fbc36f951cb4842b2903ed53be
Unified Split

Showing with 22 additions and 6 deletions.

+8 −3 pdoc/__init__.py

+9 −3 pdoc/html_helpers.py

+5 −0 pdoc/test/__init__.py
diff --git a/pdoc/__init__.py b/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]

diff --git a/pdoc/html_helpers.py b/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))

diff --git a/pdoc/test/__init__.py b/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