showdoc

Display symbol documentation in notebook and website

Rendering docment Tables

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

source

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

Documentation For An Object

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

source

ShowDocRenderer

 ShowDocRenderer (sym, name:str|None=None, title_level:int=3)

Show documentation for sym

source

BasicMarkdownRenderer

 BasicMarkdownRenderer (sym, name:str|None=None, title_level:int=3)

Markdown renderer for show_doc

source

show_doc

 show_doc (sym, renderer=None, name:str|None=None, title_level:int=3)

Show signature and docstring for sym

Type Default Details
sym Symbol to document
renderer NoneType None Optional renderer (defaults to markdown)
name str | None None Optionally override displayed name of sym
title_level int 3 Heading level to use for symbol name

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

Numpy Docstrings

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

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.

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

Class properties also work with showdoc.

Pluggable renderers

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.

source

BasicHtmlRenderer

 BasicHtmlRenderer (sym, name:str|None=None, title_level:int=3)

Simple HTML renderer for show_doc

source

doc

 doc (elt)

Show show_doc info along with link to docs

source

showdoc_nm

 showdoc_nm (tree)

Get the fully qualified name for showdoc.

Other helpers

source