Merge pull request #969 from seeM/fix-showdoc-numpy

fix: `show_doc` includes parsed sections from numpy docstrings

Author: hamelsmu

nbdev/_modidx.py

@@ -281,8 +281,8 @@
                                'nbdev.showdoc.ShowDocRenderer': ('09_API/showdoc.html#showdocrenderer', 'nbdev/showdoc.py'),
                                'nbdev.showdoc.ShowDocRenderer.__init__': ('09_API/showdoc.html#__init__', 'nbdev/showdoc.py'),
                                'nbdev.showdoc._bold': ('09_API/showdoc.html#_bold', 'nbdev/showdoc.py'),
-                               'nbdev.showdoc._escape_fn': ('09_API/showdoc.html#_escape_fn', 'nbdev/showdoc.py'),
-                               'nbdev.showdoc._escape_pipe': ('09_API/showdoc.html#_escape_pipe', 'nbdev/showdoc.py'),
+                               'nbdev.showdoc._docstring': ('09_API/showdoc.html#_docstring', 'nbdev/showdoc.py'),
+                               'nbdev.showdoc._escape_markdown': ('09_API/showdoc.html#_escape_markdown', 'nbdev/showdoc.py'),
                                'nbdev.showdoc._ext_link': ('09_API/showdoc.html#_ext_link', 'nbdev/showdoc.py'),
                                'nbdev.showdoc._f_name': ('09_API/showdoc.html#_f_name', 'nbdev/showdoc.py'),
                                'nbdev.showdoc._fmt_anno': ('09_API/showdoc.html#_fmt_anno', 'nbdev/showdoc.py'),

nbdev/showdoc.py

@@ -26,20 +26,19 @@ def _non_empty_keys(d:dict): return L([k for k,v in d.items() if v != inspect._e
 def _bold(s): return f'**{s}**' if s.strip() else s
 
 # %% ../nbs/09_API/08_showdoc.ipynb 7
-def _escape_pipe(s): return re.sub(r'(\\)?\|', '\|', s)
+def _escape_markdown(s):
+    for c in '|^': s = re.sub(rf'\\?\{c}', f'\{c}', s)
+    return s.replace('\n', '<br>')
 
 # %% ../nbs/09_API/08_showdoc.ipynb 9
-def _escape_fn(s): return re.sub(r'(?<!\\)\^\[', '\^[', s)
-
-# %% ../nbs/09_API/08_showdoc.ipynb 11
 def _maybe_nm(o): 
     if (o == inspect._empty): return ''
-    else: return o.__name__ if hasattr(o, '__name__') else _escape_fn(_escape_pipe(str(o)))
+    else: return o.__name__ if hasattr(o, '__name__') else _escape_markdown(str(o))
 
-# %% ../nbs/09_API/08_showdoc.ipynb 13
+# %% ../nbs/09_API/08_showdoc.ipynb 11
 def _list2row(l:list): return '| '+' | '.join([_maybe_nm(o) for o in l]) + ' |'
 
-# %% ../nbs/09_API/08_showdoc.ipynb 15
+# %% ../nbs/09_API/08_showdoc.ipynb 13
 class DocmentTbl:
     # this is the column order we want these items to appear
     _map = OrderedDict({'anno':'Type', 'default':'Default', 'docment':'Details'})
@@ -109,7 +108,12 @@ def __eq__(self,other): return self.__str__() == str(other).strip()
     __str__ = _repr_markdown_
     __repr__ = basic_repr()
 
-# %% ../nbs/09_API/08_showdoc.ipynb 30
+# %% ../nbs/09_API/08_showdoc.ipynb 28
+def _docstring(sym):
+    npdoc = parse_docstring(sym)
+    return '\n\n'.join([npdoc['Summary'], npdoc['Extended']]).strip()
+
+# %% ../nbs/09_API/08_showdoc.ipynb 29
 def _fullname(o):
     module,name = getattr(o, "__module__", None),qual_name(o)
     return name if module is None or module in ('__main__','builtins') else module + '.' + name
@@ -124,13 +128,13 @@ def __init__(self, sym, name:str|None=None, title_level:int=3):
         self.isfunc = inspect.isfunction(sym)
         try: self.sig = signature_ex(sym, eval_str=True)
         except (ValueError,TypeError): self.sig = None
-        self.docs = docstring(sym)
+        self.docs = _docstring(sym)
         self.dm = DocmentTbl(sym)
         self.fn = _fullname(sym)
 
     __repr__ = basic_repr()
 
-# %% ../nbs/09_API/08_showdoc.ipynb 31
+# %% ../nbs/09_API/08_showdoc.ipynb 30
 def _f_name(o): return f'<function {o.__name__}>' if isinstance(o, FunctionType) else None
 def _fmt_anno(o): return inspect.formatannotation(o).strip("'").replace(' ','')
 
@@ -143,7 +147,7 @@ def _show_param(param):
     if default is not inspect._empty: res += f'={_f_name(default) or repr(default)}'
     return res
 
-# %% ../nbs/09_API/08_showdoc.ipynb 33
+# %% ../nbs/09_API/08_showdoc.ipynb 32
 def _fmt_sig(sig):
     if sig is None: return ''
     p = {k:v for k,v in sig.parameters.items()}
@@ -156,7 +160,7 @@ def _wrap_sig(s):
     indent = pad + ' ' * (s.find('(') + 1)
     return fill(s, width=80, initial_indent=pad, subsequent_indent=indent)
 
-# %% ../nbs/09_API/08_showdoc.ipynb 35
+# %% ../nbs/09_API/08_showdoc.ipynb 34
 def _ext_link(url, txt, xtra=""): return f'[{txt}]({url}){{target="_blank" {xtra}}}'
 
 class BasicMarkdownRenderer(ShowDocRenderer):
@@ -174,7 +178,7 @@ def _repr_markdown_(self):
         return doc
     __repr__=__str__=_repr_markdown_
 
-# %% ../nbs/09_API/08_showdoc.ipynb 36
+# %% ../nbs/09_API/08_showdoc.ipynb 35
 def show_doc(sym,  # Symbol to document
              renderer=None,  # Optional renderer (defaults to markdown)
              name:str|None=None,  # Optionally override displayed name of `sym`
@@ -188,7 +192,7 @@ def show_doc(sym,  # Symbol to document
     if isinstance(sym, TypeDispatch): pass
     else:return renderer(sym or show_doc, name=name, title_level=title_level)
 
-# %% ../nbs/09_API/08_showdoc.ipynb 52
+# %% ../nbs/09_API/08_showdoc.ipynb 51
 def _html_link(url, txt): return f'<a href="{url}" target="_blank" rel="noreferrer noopener">{txt}</a>'
 
 class BasicHtmlRenderer(ShowDocRenderer):
@@ -208,17 +212,17 @@ def doc(self):
         if docs is not None: res += '\n<p>' +_html_link(docs, "Show in docs") + '</p>'
         display(HTML(res))
 
-# %% ../nbs/09_API/08_showdoc.ipynb 53
+# %% ../nbs/09_API/08_showdoc.ipynb 52
 def doc(elt):
     "Show `show_doc` info along with link to docs"
     BasicHtmlRenderer(elt).doc()
 
-# %% ../nbs/09_API/08_showdoc.ipynb 59
+# %% ../nbs/09_API/08_showdoc.ipynb 58
 def showdoc_nm(tree):
     "Get the fully qualified name for showdoc."
     return ifnone(patch_name(tree), tree.name)
 
-# %% ../nbs/09_API/08_showdoc.ipynb 63
+# %% ../nbs/09_API/08_showdoc.ipynb 62
 def colab_link(path):
     "Get a link to the notebook at `path` on Colab"
     from IPython.display import Markdown

nbs/09_API/08_showdoc.ipynb

@@ -12,7 +12,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "04b59a7c",
+   "id": "1b5b9e13",
    "metadata": {},
    "source": [
     "# showdoc\n",
@@ -86,12 +86,14 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "ff688058",
+   "id": "d6d55b8a",
    "metadata": {},
    "outputs": [],
    "source": [
     "#|export\n",
-    "def _escape_pipe(s): return re.sub(r'(\\\\)?\\|', '\\|', s)"
+    "def _escape_markdown(s):\n",
+    "    for c in '|^': s = re.sub(rf'\\\\?\\{c}', f'\\{c}', s)\n",
+    "    return s.replace('\\n', '<br>')"
    ]
   },
   {
@@ -102,32 +104,12 @@
    "outputs": [],
    "source": [
     "#|hide\n",
-    "test_eq(_escape_pipe('|'), '\\|')\n",
-    "test_eq(_escape_pipe('\\|'), '\\|')"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "75d3bf23-b88a-4ba0-afd9-df3c50be98a1",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "#|export\n",
-    "def _escape_fn(s): return re.sub(r'(?<!\\\\)\\^\\[', '\\^[', s)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5a63bb29-30d0-4851-b5fa-cc319e8e6af9",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "#|hide\n",
-    "test_eq(_escape_fn(' ^[_'), ' \\^[_')\n",
-    "test_eq(_escape_fn('foo ^[_'), 'foo \\^[_')\n",
-    "test_eq(_escape_fn(' \\^[_'), ' \\^[_') #if it is already escaped leave it alone"
+    "test_eq(_escape_markdown('|'), '\\|')\n",
+    "test_eq(_escape_markdown('\\|'), '\\|')\n",
+    "test_eq(_escape_markdown(' ^[_'), ' \\^[_') # footnotes\n",
+    "test_eq(_escape_markdown('foo ^[_'), 'foo \\^[_')\n",
+    "test_eq(_escape_markdown(' \\^[_'), ' \\^[_') #if it is already escaped leave it alone\n",
+    "test_eq(_escape_markdown('a long\\nsentence'), 'a long<br>sentence')"
    ]
   },
   {
@@ -140,7 +122,7 @@
     "#|export\n",
     "def _maybe_nm(o): \n",
     "    if (o == inspect._empty): return ''\n",
-    "    else: return o.__name__ if hasattr(o, '__name__') else _escape_fn(_escape_pipe(str(o)))"
+    "    else: return o.__name__ if hasattr(o, '__name__') else _escape_markdown(str(o))"
    ]
   },
   {
@@ -506,6 +488,19 @@
     "Render the signature as well as the `docments` to show complete documentation for an object."
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cae94920",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#|export\n",
+    "def _docstring(sym):\n",
+    "    npdoc = parse_docstring(sym)\n",
+    "    return '\\n\\n'.join([npdoc['Summary'], npdoc['Extended']]).strip()"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -528,7 +523,7 @@
     "        self.isfunc = inspect.isfunction(sym)\n",
     "        try: self.sig = signature_ex(sym, eval_str=True)\n",
     "        except (ValueError,TypeError): self.sig = None\n",
-    "        self.docs = docstring(sym)\n",
+    "        self.docs = _docstring(sym)\n",
     "        self.dm = DocmentTbl(sym)\n",
     "        self.fn = _fullname(sym)\n",
     "\n",
@@ -700,16 +695,6 @@
        "\n",
        "This is another line of the docstring.\n",
        "\n",
-       "Parameters\n",
-       "----------\n",
-       "x : int\n",
-       "    the parameter x\n",
-       "    \n",
-       "Returns\n",
-       "-------\n",
-       "None\n",
-       "    this function doesn't return anything\n",
-       "\n",
        "|    | **Type** | **Default** | **Details** |\n",
        "| -- | -------- | ----------- | ----------- |\n",
        "| x | int | 1 | the parameter x |\n",
@@ -726,16 +711,6 @@
        "\n",
        "This is another line of the docstring.\n",
        "\n",
-       "Parameters\n",
-       "----------\n",
-       "x : int\n",
-       "    the parameter x\n",
-       "    \n",
-       "Returns\n",
-       "-------\n",
-       "None\n",
-       "    this function doesn't return anything\n",
-       "\n",
        "|    | **Type** | **Default** | **Details** |\n",
        "| -- | -------- | ----------- | ----------- |\n",
        "| x | int | 1 | the parameter x |\n",
@@ -1035,7 +1010,7 @@
        "<hr/>\n",
        "<h3>show_doc</h3>\n",
        "<blockquote><pre><code>show_doc(sym, renderer=None, name:Optional[str]=None, title_level:int=3)</code></pre></blockquote><p>Show signature and docstring for `sym`</p>\n",
-       "<p><a href=\"https://nbdev.fast.ai//showdoc.html#show_doc\" target=\"_blank\" rel=\"noreferrer noopener\">Show in docs</a></p>"
+       "<p><a href=\"https://nbdev.fast.ai/09_API/showdoc.html#show_doc\" target=\"_blank\" rel=\"noreferrer noopener\">Show in docs</a></p>"
       ],
       "text/plain": [
        "<IPython.core.display.HTML object>"