🏳️‍⚧️ Transdoc 🏳️‍⚧️

Transform your documentation by embedding results from Python function calls.

Installation

pip install transdoc

To install handlers for Python, run pip install transdoc[python] instead.

Usage

Rule functions

Rules are defined using simple Python functions that return strings.

# rules.py
def my_rule() -> str:
    '''
    A simple rule for rewriting docstrings
    '''
    return "This text was added by Transdoc!"

Rules can take arbitrary arguments.

# rules.py
def repeat(text: str, n: int = 2) -> str:
    '''
    Repeat the given text any number of times.
    '''
    return " ".join([text] * n)

def mdn_link(e: str) -> str:
    '''
    Return a Markdown-formatted link to the MDN Web Docs for the given HTML
    element.
    '''
    return (
        f"[`<{e}>`]"
        f"(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/{e})"
    )

Calling rule functions

Any text placed within {{ double-braces }} is treated as a call to a rule function.

Hello world!
{{my_rule}}

Transforming this input will produce the following output.

Hello world!
This text was added by Transdoc!

Rule functions can be called using Python-like syntax.

{{repeat('Hi!', n=3)}}

Hi! Hi! Hi!

Since passing a single string as an argument is so common, Transdoc adds a special syntax for this. Simply place the string argument in square brackets.

In HTML, links can be created using the anchor
({{mdn_link[a]}}) element.

In HTML, links can be created using the anchor
([`<a>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)) element.

Transforming documentation in source code

Transdoc can also be used to transform documentation in source, by using a handler for your desired language. For more information, see the page on handlers.