showdoc

Display symbol documentation in notebook and website

Rendering docment Tables

Render nicely formatted tables that shows docments for any function or method.

test_eq(_maybe_nm(list), 'list')
test_eq(_maybe_nm('fastai'), 'fastai')

---

DocmentTbl

 DocmentTbl (obj, verbose=True, returns=True)

Compute the docment table string

DocmentTbl can render a markdown table showing docments if appropriate. This is an example of how a docments table will render for a function:

def _f(a,      # description of param a 
       b=True, # description of param b
       c:str=None
       ) -> int: ...

_dm = DocmentTbl(_f)
_dm

	Type	Default	Details
a			description of param a
b	bool	True	description of param b
c	str	None
Returns	int

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:

def _f(a, 
        b, #param b
        c  #param c
       ): ...

_dm2 = DocmentTbl(_f)
_dm2

	Details
a
b	param b
c	param c

DocmentTbl also works on classes. By default, the __init__ will be rendered:

class _Test:
    def __init__(self, 
                 a,      # description of param a 
                 b=True, # description of param b
                 c:str=None):
        ...
        
    def foo(self, 
            c:int,      # description of param c
            d=True, # description of param d
           ):
        ...

DocmentTbl(_Test)

	Type	Default	Details
a			description of param a
b	bool	True	description of param b
c	str	None

You can also pass a method to be rendered as well:

DocmentTbl(_Test.foo)

	Type	Default	Details
c	int		description of param c
d	bool	True	description of param d

Show Complete Documentation For An Object

Render the signature as well as the docments to show complete documentation for an object.

---

ShowDocRenderer

 ShowDocRenderer (sym, disp:bool=True)

Show documentation for sym

---

BasicMarkdownRenderer

 BasicMarkdownRenderer (sym, disp:bool=True)

Show documentation for sym

---

show_doc

 show_doc (sym, disp=True, renderer=None)

You can use show_doc to document apis of functions, classes or methods:

---

f

 f (x:int=1)

func docstring

Warning

If you are using a version of python that is older than 3.10, type hints might be rendered as strings when running show_doc. We recommend upgrading to python 3.10 locally if possible so you can preview docs without this artifact. We have set the version of python to be 3.10 .github/workflows/deploy.yaml for this reason as well.

---

f

 f (x:int=1)

func docstring

	Type	Default	Details
x	int	1	the parameter x
Returns	None		this function doesn’t return anything

Numpy Docstrings

if you have numpy docstrings instead of docments, show_doc will attempt to parse and render those just like docments:

---

f

 f (x=1)

func docstring in the numpy style.

	Type	Default	Details
x	int	1	the parameter x
Returns	None		this function doesn’t return anything

Warning

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.

show_doc on Classes

show_doc works on Classes, too including when you use @patch:

---

Foo

 Foo (d:str, e:int)

This is the docstring for the init method

You can define methods for the class Foo with @patch which is convenient in allowing you to break up code for documentation in notebooks:

@patch
def a_method(self:Foo, 
             a:list, # param a
             b:dict,c):
        "This is a method"
        ...

_res = show_doc(Foo.a_method)
_res

---

Foo.a_method

 Foo.a_method (a:list, b:dict, c)

This is a method

	Type	Details
a	list	param a
b	dict
c

Class properties also work with showdoc:

_res = show_doc(Foo.some_prop)
_res

---

Foo.some_prop

This is a class property.

---

BasicHtmlRenderer

 BasicHtmlRenderer (sym, disp:bool=True)

Show documentation for sym

---

F

F(x: int = 1)

class docstring

_res = show_doc(F.class_method)
_res

---

F.class_method

 F.class_method (foo:str, bar:int)

This is a class method.

	Type	Details
foo	str	docment for parameter foo
bar	int

---

F.regular_method

 F.regular_method (baz:bool=True)

This is a regular method

	Type	Default	Details
baz	bool	True	docment for parameter baz

---

showdoc_nm

 showdoc_nm (tree)

Get the fully qualified name for showdoc.