render¶

Module for automate the generation of markdown docs. Documenting individual functions, objects, and classes is supported, as well as modules.

Functions¶

markdown¶

def markdown(obj):

Return object's __repr_markdown__

This is useful as a function that can be passed around to get the markdown representation of various objects.

Parameters¶

obj: An object implementing __repr_markdown__

Returns¶

The result of calling __repr_markdown__

Examples¶

from mkdocs_apidoc.render import markdown

class A:
    def __repr_markdown__(self):
        return "# I am the **markdown** representation of A!"

print(markdown(A()))

# I am the **markdown** representation of A!

make_converter¶

def make_converter(structure: Callable[[Any], ~T], unstructure: Callable[[~T], str]) -> typing.Callable[[str], str]:

Create a conversion function

The resulting function will take a string, the name of an object and structure it. Structured object will then be unstructured.

The Return type of structure must match the input type of unstructure.

Parameters¶

structure: A function which takes a python object, and structures it to a known type.
unstructure: A function which converts an object to a markdown representation.

Returns¶

A conversion function

Example¶

from mkdocs_apidoc.render import make_converter

def parse_docstring(s: str) -> str:
    return s.__doc__

def charcount(s: str) -> str:
    return f"Docstring is {len(s)} lines long, here it is ---> {s}"

converter = make_converter(parse_docstring, charcount)
print(converter("itertools.count"))

Docstring is 205 lines long, here it is ---> Return a count object whose .__next__() method returns consecutive values.

Equivalent to:
    def count(firstval=0, step=1):
        x = firstval
        while 1:
            yield x
            x += step

render_page¶

def render_page(page: str) -> str:

render the page

Parameters¶

page: The page to be rendered

Returns¶

The rendered page

Example¶

from mkdocs_apidoc.render import render_page

page = '''
# Hi i'm an example markdown file
{{ auto_object('collections.deque') }}

## you can keep doing stuff here too

Did you know the type of `collections.namedtuple` is {{ typeof('collections.namedtuple') }} ???
'''
print(render_page(page))

# Hi i'm an example markdown file
deque([iterable[, maxlen]]) --> deque object

A list-like sequence optimized for data accesses near its endpoints.

## you can keep doing stuff here too

Did you know the type of `collections.namedtuple` is function ???