nbs/api/08_showdoc.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5b3e6248",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|default_exp showdoc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b5b9e13",
   "metadata": {},
   "source": [
    "# showdoc\n",
    "> Display symbol documentation in notebook and website\n",
    "- order: 8"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7f371f15",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "from __future__ import annotations\n",
    "from nbdev.doclinks import *\n",
    "from nbdev.config import get_config\n",
    "\n",
    "from fastcore.docments import *\n",
    "from fastcore.utils import *\n",
    "\n",
    "from importlib import import_module\n",
    "import inspect, sys\n",
    "from collections import OrderedDict\n",
    "from textwrap import fill\n",
    "from types import FunctionType"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37779036-032f-41cc-bedb-d928f1a25df7",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "from inspect import Parameter\n",
    "from fastcore.test import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d012c7e4",
   "metadata": {},
   "source": [
    "## Rendering docment Tables"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6c573b6-73cf-4c5e-b4a6-989b62071cc1",
   "metadata": {},
   "source": [
    "Render nicely formatted tables that shows `docments` for any function or method.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5de6dc35-565d-4847-8505-b9feb680cb1a",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _non_empty_keys(d:dict): return L([k for k,v in d.items() if v != inspect._empty])\n",
    "def _bold(s): return f'**{s}**' if s.strip() else s"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d6d55b8a",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _escape_markdown(s):\n",
    "    for c in '|^': s = re.sub(rf'\\\\?\\{c}', rf'\\{c}', s)\n",
    "    return s.replace('\\n', '<br>')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "418f8192",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "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')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8ea735b2-a5ee-4176-8143-add7ab08a3cd",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _maybe_nm(o):\n",
    "    if (o == inspect._empty): return ''\n",
    "    else: return o.__name__ if hasattr(o, '__name__') else _escape_markdown(str(o))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "908341c8-dfb4-4e05-9122-30dcae4bc130",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "test_eq(_maybe_nm(list), 'list')\n",
    "test_eq(_maybe_nm('fastai'), 'fastai')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "63418af8-3f68-4301-9da3-da5787f8c257",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _list2row(l:list): return '| '+' | '.join([_maybe_nm(o) for o in l]) + ' |'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b74936bc-a38d-4e98-a4f8-3c97a8bd8e86",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "test_eq(_list2row(['Hamel', 'Jeremy']), '| Hamel | Jeremy |')\n",
    "test_eq(_list2row([inspect._empty, bool, 'foo']), '|  | bool | foo |')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7eff0337-25ff-4fbe-afe0-a7ef0788ebf9",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "class DocmentTbl:\n",
    "    # this is the column order we want these items to appear\n",
    "    _map = OrderedDict({'anno':'Type', 'default':'Default', 'docment':'Details'})\n",
    "\n",
    "    def __init__(self, obj, verbose=True, returns=True):\n",
    "        \"Compute the docment table string\"\n",
    "        self.verbose = verbose\n",
    "        self.returns = False if isdataclass(obj) else returns\n",
    "        try: self.params = L(signature_ex(obj, eval_str=True).parameters.keys())\n",
    "        except (ValueError,TypeError): self.params=[]\n",
    "        try: _dm = docments(obj, full=True, returns=returns)\n",
    "        except: _dm = {}\n",
    "        if 'self' in _dm: del _dm['self']\n",
    "        for d in _dm.values(): d['docment'] = ifnone(d['docment'], inspect._empty)\n",
    "        self.dm = _dm\n",
    "\n",
    "    @property\n",
    "    def _columns(self):\n",
    "        \"Compute the set of fields that have at least one non-empty value so we don't show tables empty columns\"\n",
    "        cols = set(flatten(L(self.dm.values()).filter().map(_non_empty_keys)))\n",
    "        candidates = self._map if self.verbose else {'docment': 'Details'}\n",
    "        return OrderedDict({k:v for k,v in candidates.items() if k in cols})\n",
    "\n",
    "    @property\n",
    "    def has_docment(self): return 'docment' in self._columns and self._row_list\n",
    "\n",
    "    @property\n",
    "    def has_return(self): return self.returns and bool(_non_empty_keys(self.dm.get('return', {})))\n",
    "\n",
    "    def _row(self, nm, props):\n",
    "        \"unpack data for single row to correspond with column names.\"\n",
    "        return [nm] + [props[c] for c in self._columns]\n",
    "\n",
    "    @property\n",
    "    def _row_list(self):\n",
    "        \"unpack data for all rows.\"\n",
    "        ordered_params = [(p, self.dm[p]) for p in self.params if p != 'self' and p in self.dm]\n",
    "        return L([self._row(nm, props) for nm,props in ordered_params])\n",
    "\n",
    "    @property\n",
    "    def _hdr_list(self): return ['  '] + [_bold(l) for l in L(self._columns.values())]\n",
    "\n",
    "    @property\n",
    "    def hdr_str(self):\n",
    "        \"The markdown string for the header portion of the table\"\n",
    "        md = _list2row(self._hdr_list)\n",
    "        return md + '\\n' + _list2row(['-' * len(l) for l in self._hdr_list])\n",
    "\n",
    "    @property\n",
    "    def params_str(self):\n",
    "        \"The markdown string for the parameters portion of the table.\"\n",
    "        return '\\n'.join(self._row_list.map(_list2row))\n",
    "\n",
    "    @property\n",
    "    def return_str(self):\n",
    "        \"The markdown string for the returns portion of the table.\"\n",
    "        return _list2row(['**Returns**']+[_bold(_maybe_nm(self.dm['return'][c])) for c in self._columns])\n",
    "\n",
    "    def _repr_markdown_(self):\n",
    "        if not self.has_docment: return ''\n",
    "        _tbl = [self.hdr_str, self.params_str]\n",
    "        if self.has_return: _tbl.append(self.return_str)\n",
    "        return '\\n'.join(_tbl)\n",
    "\n",
    "    def __eq__(self,other): return self.__str__() == str(other).strip()\n",
    "\n",
    "    __str__ = _repr_markdown_\n",
    "    __repr__ = basic_repr()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6bf2c677-d0d5-42cf-a2c7-fcbdec725720",
   "metadata": {},
   "source": [
    "`DocmentTbl` can render a markdown table showing `docments` if appropriate.  This is an example of how a `docments` table will render for a function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ac9a8ddc-9fe6-48c6-b2a5-bc0f1a7a0926",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "|    | **Type** | **Default** | **Details** |\n",
       "| -- | -------- | ----------- | ----------- |\n",
       "| a |  |  | description of param a |\n",
       "| b | bool | True | description of param b |\n",
       "| c | str | None |  |\n",
       "| **Returns** | **int** |  |  |"
      ],
      "text/plain": [
       "<__main__.DocmentTbl>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def _f(a,      # description of param a\n",
    "       b=True, # description of param b\n",
    "       c:str=None\n",
    "       ) -> int: ...\n",
    "\n",
    "_dm = DocmentTbl(_f)\n",
    "_dm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c44d2bba-377e-4f72-9c4e-1b583acaedb7",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "_exp_res=\"\"\"\n",
    "|    | **Type** | **Default** | **Details** |\n",
    "| -- | -------- | ----------- | ----------- |\n",
    "| a |  |  | description of param a |\n",
    "| b | bool | True | description of param b |\n",
    "| c | str | None |  |\n",
    "| **Returns** | **int** |  |  |\n",
    "\"\"\"\n",
    "\n",
    "test_eq(_dm, _exp_res)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "affcab1f-d4a6-4f0e-9f5a-da92611e7cf2",
   "metadata": {},
   "source": [
    "If one column in the table has no information, for example because there are no default values, that column will not be shown.  In the below example, the **Default** column, will not be shown.  Additionally, if the return of the function is not annotated the **Returns** row will not be rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7339ca82-b816-424f-b7f4-63b8db99cef0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "|    | **Details** |\n",
       "| -- | ----------- |\n",
       "| a |  |\n",
       "| b | param b |\n",
       "| c | param c |"
      ],
      "text/plain": [
       "<__main__.DocmentTbl>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def _f(a,\n",
    "        b, #param b\n",
    "        c  #param c\n",
    "       ): ...\n",
    "\n",
    "_dm2 = DocmentTbl(_f)\n",
    "_dm2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b18421bf-108e-433f-b7ca-9f13749bcc42",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "_exp_res2 = \"\"\"\n",
    "|    | **Details** |\n",
    "| -- | ----------- |\n",
    "| a |  |\n",
    "| b | param b |\n",
    "| c | param c |\n",
    "\"\"\"\n",
    "\n",
    "test_eq(_dm2, _exp_res2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9e7a6d5-4fff-4df2-8f35-f4b4be968d28",
   "metadata": {},
   "source": [
    "`DocmentTbl` also works on classes.  By default, the `__init__` will be rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "669f06c4-cd96-40d3-bae8-ed01fa88fc77",
   "metadata": {},
   "outputs": [],
   "source": [
    "class _Test:\n",
    "    def __init__(self,\n",
    "                 a,      # description of param a\n",
    "                 b=True, # description of param b\n",
    "                 c:str=None):\n",
    "        ...\n",
    "\n",
    "    def foo(self,\n",
    "            c:int,      # description of param c\n",
    "            d=True, # description of param d\n",
    "           ):\n",
    "        ..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3230ab3-5902-48bb-925a-99cfea7d6a37",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "|    | **Type** | **Default** | **Details** |\n",
       "| -- | -------- | ----------- | ----------- |\n",
       "| a |  |  | description of param a |\n",
       "| b | bool | True | description of param b |\n",
       "| c | str | None |  |"
      ],
      "text/plain": [
       "<__main__.DocmentTbl>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "DocmentTbl(_Test)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d2debf2b-6c58-4966-8600-8e6cbba3b3fd",
   "metadata": {},
   "source": [
    "You can also pass a method to be rendered as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c499a450-0182-4ad0-8cab-f10f190a7545",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "|    | **Type** | **Default** | **Details** |\n",
       "| -- | -------- | ----------- | ----------- |\n",
       "| c | int |  | description of param c |\n",
       "| d | bool | True | description of param d |"
      ],
      "text/plain": [
       "<__main__.DocmentTbl>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "DocmentTbl(_Test.foo)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c113ea93-9e0f-4b52-a5fd-87ed0de24c90",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "_exp_res3 = \"\"\"\n",
    "|    | **Type** | **Default** | **Details** |\n",
    "| -- | -------- | ----------- | ----------- |\n",
    "| c | int |  | description of param c |\n",
    "| d | bool | True | description of param d |\n",
    "\"\"\"\n",
    "\n",
    "test_eq(DocmentTbl(_Test.foo), _exp_res3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "773b5bfb",
   "metadata": {},
   "source": [
    "## Documentation For An Object"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0eb7314a-675d-4fd8-8f9b-425666e1bd86",
   "metadata": {},
   "source": [
    "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,
   "id": "aba0b132",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _fullname(o):\n",
    "    module,name = getattr(o, \"__module__\", None),qual_name(o)\n",
    "    return name if module is None or module in ('__main__','builtins') else module + '.' + name\n",
    "\n",
    "class ShowDocRenderer:\n",
    "    def __init__(self, sym, name:str|None=None, title_level:int=3):\n",
    "        \"Show documentation for `sym`\"\n",
    "        sym = getattr(sym, '__wrapped__', sym)\n",
    "        sym = getattr(sym, 'fget', None) or getattr(sym, 'fset', None) or sym\n",
    "        store_attr()\n",
    "        self.nm = name or qual_name(sym)\n",
    "        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.dm = DocmentTbl(sym)\n",
    "        self.fn = _fullname(sym)\n",
    "\n",
    "    __repr__ = basic_repr()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "231548de",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _f_name(o): return f'<function {o.__name__}>' if isinstance(o, FunctionType) else None\n",
    "def _fmt_anno(o): return inspect.formatannotation(o).strip(\"'\").replace(' ','')\n",
    "\n",
    "def _show_param(param):\n",
    "    \"Like `Parameter.__str__` except removes: quotes in annos, spaces, ids in reprs\"\n",
    "    kind,res,anno,default = param.kind,param._name,param._annotation,param._default\n",
    "    kind = '*' if kind==inspect._VAR_POSITIONAL else '**' if kind==inspect._VAR_KEYWORD else ''\n",
    "    res = kind+res\n",
    "    if anno is not inspect._empty: res += f':{_f_name(anno) or _fmt_anno(anno)}'\n",
    "    if default is not inspect._empty: res += f'={_f_name(default) or repr(default)}'\n",
    "    return res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7deac6db",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "def _func(): pass\n",
    "p = Parameter('foo', Parameter.POSITIONAL_OR_KEYWORD, default=_func, annotation='Callable')\n",
    "test_eq(_show_param(p), 'foo:Callable=<function _func>')\n",
    "p = p.replace(annotation=_func)\n",
    "test_eq(_show_param(p), 'foo:<function _func>=<function _func>')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b406e38f-25c8-46e4-bb65-f039cb7b5a2a",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _fmt_sig(sig):\n",
    "    if sig is None: return ''\n",
    "    p = {k:v for k,v in sig.parameters.items()}\n",
    "    _params = [_show_param(p[k]) for k in p.keys() if k != 'self']\n",
    "    return \"(\" + ', '.join(_params)  + \")\"\n",
    "\n",
    "def _wrap_sig(s):\n",
    "    \"wrap a signature to appear on multiple lines if necessary.\"\n",
    "    pad = '> ' + ' ' * 5\n",
    "    indent = pad + ' ' * (s.find('(') + 1)\n",
    "    return fill(s, width=80, initial_indent=pad, subsequent_indent=indent)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cd1aa1d7-d545-4a76-9de8-394beb4f2b8e",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "def _long_f(a_param, b_param=True, c_param:str='Some quite long value', d:int=2, e:bool=False):\n",
    "    \"A docstring\"\n",
    "    ...\n",
    "\n",
    "_res = \">      (a_param, b_param=True, c_param:str='Some quite long value', d:int=2,\\n>       e:bool=False)\"\n",
    "_sig = _fmt_sig(signature_ex(_long_f, eval_str=True))\n",
    "test_eq(_wrap_sig(_sig), _res)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "abe98f5c",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def _ext_link(url, txt, xtra=\"\"): return f'[{txt}]({url}){{target=\"_blank\" {xtra}}}'\n",
    "\n",
    "class BasicMarkdownRenderer(ShowDocRenderer):\n",
    "    \"Markdown renderer for `show_doc`\"\n",
    "    def _repr_markdown_(self):\n",
    "        doc = '---\\n\\n'\n",
    "        src = NbdevLookup().code(self.fn)\n",
    "        if src: doc += _ext_link(src, 'source', 'style=\"float:right; font-size:smaller\"') + '\\n\\n'\n",
    "        h = '#'*self.title_level\n",
    "        doc += f'{h} {self.nm}\\n\\n'\n",
    "        sig = _wrap_sig(f\"{self.nm} {_fmt_sig(self.sig)}\") if self.sig else ''\n",
    "        doc += f'{sig}'\n",
    "        if self.docs: doc += f\"\\n\\n*{self.docs}*\"\n",
    "        if self.dm.has_docment: doc += f\"\\n\\n{self.dm}\"\n",
    "        return doc\n",
    "    __repr__=__str__=_repr_markdown_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1256ef79",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def show_doc(sym,  # Symbol to document\n",
    "             renderer=None,  # Optional renderer (defaults to markdown)\n",
    "             name:str|None=None,  # Optionally override displayed name of `sym`\n",
    "             title_level:int=3):  # Heading level to use for symbol name\n",
    "    \"Show signature and docstring for `sym`\"\n",
    "    if renderer is None: renderer = get_config().get('renderer', None)\n",
    "    if renderer is None: renderer=BasicMarkdownRenderer\n",
    "    elif isinstance(renderer,str):\n",
    "        p,m = renderer.rsplit('.', 1)\n",
    "        renderer = getattr(import_module(p), m)\n",
    "    if isinstance_str(sym, \"Function\"): pass\n",
    "    elif isinstance_str(sym, \"TypeDispatch\"): pass  # use _str as TypeDispatch will be removed from fastcore\n",
    "    else:return renderer(sym or show_doc, name=name, title_level=title_level)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8725b5f0",
   "metadata": {},
   "source": [
    "You can use `show_doc` to document apis of functions, classes or methods."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "620d814f",
   "metadata": {},
   "source": [
    "### Numpy Docstrings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d88c9513-2d6b-49ed-ae68-37330753c98c",
   "metadata": {},
   "source": [
    "if you have [numpy docstrings](https://numpydoc.readthedocs.io/en/latest/format.html) instead of `docments`, `show_doc` will attempt to parse and render those just like `docments`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8b9e9b32",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### f\n",
       "\n",
       ">      f (x=1)\n",
       "\n",
       "func docstring in the numpy style.\n",
       "\n",
       "This is another line of the docstring.\n",
       "\n",
       "|    | **Type** | **Default** | **Details** |\n",
       "| -- | -------- | ----------- | ----------- |\n",
       "| x | int | 1 | the parameter x |\n",
       "| **Returns** | **None** |  | **this function doesn't return anything** |"
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### f\n",
       "\n",
       ">      f (x=1)\n",
       "\n",
       "func docstring in the numpy style.\n",
       "\n",
       "This is another line of the docstring.\n",
       "\n",
       "|    | **Type** | **Default** | **Details** |\n",
       "| -- | -------- | ----------- | ----------- |\n",
       "| x | int | 1 | the parameter x |\n",
       "| **Returns** | **None** |  | **this function doesn't return anything** |"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|hide\n",
    "def f(x=1):\n",
    "    \"\"\"\n",
    "    func docstring in the numpy style.\n",
    "\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",
    "\n",
    "show_doc(f)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f668274-4fd0-4c73-b9cf-eba4fd995543",
   "metadata": {},
   "source": [
    ":::{.callout-warning}\n",
    "\n",
    "Numpy docstring formatting is very strict.  If your docstrings do not strictly adhere to the numpy format, it will not be parsed properly and information about parameters and return values may not properly be rendered in the table below the signature.  Where possible, we recommend using `docments` to annonate your function instead.\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6256505",
   "metadata": {},
   "source": [
    "## show_doc on Classes"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c690f30b-628f-499a-a4d7-f91f872bdd34",
   "metadata": {},
   "source": [
    "`show_doc` works on Classes, too, including when you use `@patch`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1c28ec9d-29ff-497f-97b0-ca262f530cf6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### Foo\n",
       "\n",
       ">      Foo (d:str, e:int)\n",
       "\n",
       "This is the docstring for the `__init__` method"
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### Foo\n",
       "\n",
       ">      Foo (d:str, e:int)\n",
       "\n",
       "This is the docstring for the `__init__` method"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|hide\n",
    "class Foo:\n",
    "    def __init__(self, d:str,e:int):\n",
    "        \"This is the docstring for the `__init__` method\"\n",
    "        ...\n",
    "    @property\n",
    "    def some_prop(self):\n",
    "        \"This is a class property.\"\n",
    "        return 'foo property'\n",
    "\n",
    "show_doc(Foo)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20010f4e-5f96-4929-9c1f-5fc85f7c0d5f",
   "metadata": {},
   "source": [
    "You can define methods for the class `Foo` with `@patch` which is convenient in allowing you to break up code for documentation in notebooks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3441e6c7-472b-411c-a179-b1e37dcbceac",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### Foo.a_method\n",
       "\n",
       ">      Foo.a_method (a:list, b:dict, c)\n",
       "\n",
       "This is a method\n",
       "\n",
       "|    | **Type** | **Details** |\n",
       "| -- | -------- | ----------- |\n",
       "| a | list | param a |\n",
       "| b | dict |  |\n",
       "| c |  |  |"
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### Foo.a_method\n",
       "\n",
       ">      Foo.a_method (a:list, b:dict, c)\n",
       "\n",
       "This is a method\n",
       "\n",
       "|    | **Type** | **Details** |\n",
       "| -- | -------- | ----------- |\n",
       "| a | list | param a |\n",
       "| b | dict |  |\n",
       "| c |  |  |"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|hide\n",
    "@patch\n",
    "def a_method(self:Foo,\n",
    "             a:list, # param a\n",
    "             b:dict,c):\n",
    "        \"This is a method\"\n",
    "        ...\n",
    "\n",
    "_res = show_doc(Foo.a_method)\n",
    "_res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a05a8a3c-7e89-41ff-857f-7479492fc9b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "# signature and docment should show properly when using @patch\n",
    "assert '(a:list, b:dict, c)' in str(_res)\n",
    "assert 'param a' in str(_res)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe518a59-07e4-4672-8a51-b3cc6475b4ba",
   "metadata": {},
   "source": [
    "Class properties also work with showdoc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2727145-be26-4fd1-b67c-78efae89b871",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### Foo.some_prop\n",
       "\n",
       ">      Foo.some_prop ()\n",
       "\n",
       "This is a class property."
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### Foo.some_prop\n",
       "\n",
       ">      Foo.some_prop ()\n",
       "\n",
       "This is a class property."
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|hide\n",
    "show_doc(Foo.some_prop)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73b167ff",
   "metadata": {},
   "source": [
    "## Pluggable renderers"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "361ee022",
   "metadata": {},
   "source": [
    "You can replace the default markdown show_doc renderer with custom renderers. For instance, nbdev comes with a simple example for rendering with raw HTML."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5271cd9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "def _create_html_table(table_str):\n",
    "    def split_row(row):\n",
    "        return re.findall(r'\\|(?:(?:\\\\.|[^|\\\\])*)', row)\n",
    "    \n",
    "    def unescape_cell(cell): \n",
    "        return cell.strip(' *|').replace(r'\\|', '|')\n",
    "    \n",
    "    lines = table_str.strip().split('\\n')\n",
    "    header = [f\"<th>{unescape_cell(cell)}</th>\" for cell in split_row(lines[0])]\n",
    "    rows = [[f\"<td>{unescape_cell(cell)}</td>\" for cell in split_row(line)] for line in lines[2:]]\n",
    "    \n",
    "    return f'''<table>\n",
    "    <thead><tr>{' '.join(header)}</tr></thead>\n",
    "    <tbody>{''.join(f'<tr>{\" \".join(row)}</tr>' for row in rows)}</tbody>\n",
    "    </table>'''"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a4ae5b2a",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "def _html_link(url, txt): return f'<a href=\"{url}\" target=\"_blank\" rel=\"noreferrer noopener\">{txt}</a>'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "147626ee",
   "metadata": {},
   "outputs": [],
   "source": [
    "#| export\n",
    "class BasicHtmlRenderer(ShowDocRenderer):\n",
    "    \"HTML renderer for `show_doc`\"\n",
    "    def _repr_html_(self):\n",
    "        doc = '<hr/>\\n'\n",
    "        src = NbdevLookup().code(self.fn)\n",
    "        doc += f'<h{self.title_level}>{self.nm}</h{self.title_level}>\\n'\n",
    "        sig = _fmt_sig(self.sig) if self.sig else ''\n",
    "        # Escape < and > characters in the signature\n",
    "        sig = sig.replace('<', '&lt;').replace('>', '&gt;')\n",
    "        doc += f'<blockquote><pre><code>{self.nm} {sig}</code></pre></blockquote>'\n",
    "        if self.docs:\n",
    "            doc += f\"<p><i>{self.docs}</i></p>\"\n",
    "        if src: doc += f\"<br/>{_html_link(src, 'source')}\"\n",
    "        if self.dm.has_docment: doc += _create_html_table(str(self.dm))\n",
    "        return doc\n",
    "\n",
    "    def doc(self):\n",
    "        \"Show `show_doc` info along with link to docs\"\n",
    "        from IPython.display import display,HTML\n",
    "        res = self._repr_html_()\n",
    "        display(HTML(res))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "eb1f0530",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def doc(elt):\n",
    "    \"Show `show_doc` info along with link to docs\"\n",
    "    BasicHtmlRenderer(elt).doc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37b5a903",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<hr/>\n",
       "<h3>show_doc</h3>\n",
       "<blockquote><pre><code>show_doc (sym, renderer=None, name:str|None=None, title_level:int=3)</code></pre></blockquote><p><i>Show signature and docstring for `sym`</i></p><br/><a href=\"https://github.com/fastai/nbdev/blob/master/nbdev/showdoc.py#L182\" target=\"_blank\" rel=\"noreferrer noopener\">source</a><table>\n",
       "    <thead><tr><th></th> <th>Type</th> <th>Default</th> <th>Details</th> <th></th></tr></thead>\n",
       "    <tbody><tr><td>sym</td> <td></td> <td></td> <td>Symbol to document</td> <td></td></tr><tr><td>renderer</td> <td>NoneType</td> <td>None</td> <td>Optional renderer (defaults to markdown)</td> <td></td></tr><tr><td>name</td> <td>str | None</td> <td>None</td> <td>Optionally override displayed name of `sym`</td> <td></td></tr><tr><td>title_level</td> <td>int</td> <td>3</td> <td>Heading level to use for symbol name</td> <td></td></tr></tbody>\n",
       "    </table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "#|hide\n",
    "doc(show_doc)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "059071e3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<hr/>\n",
       "<h3>F</h3>\n",
       "<blockquote><pre><code>F(x:int=1)</code></pre></blockquote><p>class docstring</p>"
      ],
      "text/plain": [
       "<__main__.BasicHtmlRenderer>"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|hide\n",
    "class F:\n",
    "    \"class docstring\"\n",
    "    def __init__(self, x:int=1): ...\n",
    "\n",
    "    @classmethod\n",
    "    def class_method(cls,\n",
    "                     foo:str, # docment for parameter foo\n",
    "                     bar:int):\n",
    "        \"This is a class method.\"\n",
    "        pass\n",
    "\n",
    "    def regular_method(self,\n",
    "                       baz:bool=True): # docment for parameter baz\n",
    "        \"This is a regular method\"\n",
    "        pass\n",
    "\n",
    "show_doc(F, renderer=BasicHtmlRenderer)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e217c559-58b6-49a5-bb58-1575a4a42ded",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### F.class_method\n",
       "\n",
       ">      F.class_method (foo:str, bar:int)\n",
       "\n",
       "This is a class method.\n",
       "\n",
       "|    | **Type** | **Details** |\n",
       "| -- | -------- | ----------- |\n",
       "| foo | str | docment for parameter foo |\n",
       "| bar | int |  |"
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### F.class_method\n",
       "\n",
       ">      F.class_method (foo:str, bar:int)\n",
       "\n",
       "This is a class method.\n",
       "\n",
       "|    | **Type** | **Details** |\n",
       "| -- | -------- | ----------- |\n",
       "| foo | str | docment for parameter foo |\n",
       "| bar | int |  |"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|hide\n",
    "_res = show_doc(F.class_method)\n",
    "_res"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2866a4b-0307-4700-9c23-a2c7de078f54",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "# There should be docments for a class method\n",
    "assert 'docment for parameter foo' in str(_res), 'No docment found for class method'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "57a1e24f-2534-41d7-ad98-ade5d42f096c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "---\n",
       "\n",
       "### F.regular_method\n",
       "\n",
       ">      F.regular_method (baz:bool=True)\n",
       "\n",
       "This is a regular method\n",
       "\n",
       "|    | **Type** | **Default** | **Details** |\n",
       "| -- | -------- | ----------- | ----------- |\n",
       "| baz | bool | True | docment for parameter baz |"
      ],
      "text/plain": [
       "---\n",
       "\n",
       "### F.regular_method\n",
       "\n",
       ">      F.regular_method (baz:bool=True)\n",
       "\n",
       "This is a regular method\n",
       "\n",
       "|    | **Type** | **Default** | **Details** |\n",
       "| -- | -------- | ----------- | ----------- |\n",
       "| baz | bool | True | docment for parameter baz |"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "#|hide\n",
    "show_doc(F.regular_method)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "35043aa7-6b60-4ddf-8949-39a78577f23d",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def showdoc_nm(tree):\n",
    "    \"Get the fully qualified name for showdoc.\"\n",
    "    return ifnone(patch_name(tree), tree.name)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cc331a84",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "import ast"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fe22731d-ad7d-4080-ac91-e0d24e8b681c",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "code=\"\"\"\n",
    "@bar\n",
    "@patch\n",
    "@foo\n",
    "def a_method(self:Foo, a:list,b:dict,c):\n",
    "    \"This is a method\"\n",
    "    ...\n",
    "\"\"\"\n",
    "\n",
    "code2=\"\"\"\n",
    "@bar\n",
    "@foo\n",
    "def a_method(self:Foo, a:list,b:dict,c):\n",
    "    \"This is a method\"\n",
    "    ...\n",
    "\"\"\"\n",
    "\n",
    "_tree = ast.parse(code).body[0]\n",
    "test_eq(showdoc_nm(_tree), 'Foo.a_method')\n",
    "\n",
    "_tree2 = ast.parse(code2).body[0]\n",
    "test_eq(showdoc_nm(_tree2), 'a_method')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4be98ffb",
   "metadata": {},
   "source": [
    "## Other helpers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e947414d",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|export\n",
    "def colab_link(path):\n",
    "    \"Get a link to the notebook at `path` on Colab\"\n",
    "    from IPython.display import Markdown\n",
    "    cfg = get_config()\n",
    "    pre = 'https://colab.research.google.com/github/'\n",
    "    res = f'{pre}{cfg.user}/{cfg.repo}/blob/{cfg.branch}/{cfg.nbs_path.name}/{path}.ipynb'\n",
    "    display(Markdown(f'[Open `{path}` in Colab]({res})'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "80e0a6cd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "[Open `index` in Colab](https://colab.research.google.com/github/fastai/nbdev/blob/master/nbs/index.ipynb)"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "colab_link('index')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac6f8e04-ff14-4978-a4ba-09f7a2b91098",
   "metadata": {},
   "source": [
    "## Test Edgecases -"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0df86ce3",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "from plum import dispatch"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bedf2b4d-4ee1-4836-ae91-416ab7c346a9",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "@dispatch\n",
    "def _typ_test(\n",
    "    a:list, # A list\n",
    "    b:str, # A second integer\n",
    ") -> float:\n",
    "    \"Perform op\"\n",
    "    return a.extend(b)\n",
    "\n",
    "@dispatch\n",
    "def _typ_test(\n",
    "    a:str, # An integer\n",
    "    b:str # A str\n",
    ") -> float:\n",
    "    \"Perform op\"\n",
    "    return str(a) + b\n",
    "\n",
    "test_eq(show_doc(_typ_test), None) # show_doc ignores dispatch at the moment"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec7a2f01",
   "metadata": {},
   "source": [
    "## Export -"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d20a1ed8",
   "metadata": {},
   "outputs": [],
   "source": [
    "#|hide\n",
    "import nbdev; nbdev. nbdev_export()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d478691b",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "python3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}