Built-in Transdoc rules

Transdoc includes a number of common rules, which can be found in the transdoc.rules module.

transdoc.rules.file_contents(path) cached

Transdoc rule that evaluates to the contents of a file.

Parameters:

Name	Type	Description	Default
path	str	Path to the file to include.	required

transdoc.rules.markdown_docs_link_rule_gen(base_url)

Creates a rule for generating Markdown-style links to a site given a base URL.

The rule can be generated using a base URL.

from transdoc.rules import docs_link_from_site
docs = docs_link_from_site("https://example.com/")

The rule can then be used as follows:

See documentation {{docs("some_function", "here")}}.

Which will produce:

See documentation [here](https://example.com/some_function).

Parameters:

Name	Type	Description	Default
base_url	str	Base URL to use for documentation site.	required

Returns:

Type	Description
`(str, Optional[str]) -> str`	A rule function that accepts a URL fragment and produces a Markdown-formatted link.

transdoc.rules.python_object_attributes_rule_gen(*, filter=None, formatter=None)

Create and return a python_object_attributes rule that uses the given formatter and/or filter.

This can be used in a list of rules as follows:

from transdoc.rules import attributes_generator

def my_custom_formatter(mod, obj, attr):
    return f"{mod}.{obj}.{attr}"

attributes = python_object_attributes_rule_gen(formatter=my_custom_formatter)

Parameters:

Name	Type	Description	Default
filter	(str, Any) -> bool	a function used to filter out unwanted attributes from the list. It should accept the name of the attribute, as well as a reference to it, then return True if the attribute should be included in the list, or False if it should be skipped. By default, this skips any attributes whose names start with an underscore (_).	None
formatter	(str, Optional[str], str) -> str	A function to format the documentation for the attribute. It should accept the module name (eg "org.serious_company"), the object name (eg "FizzBuzz"), and the attribute name (eg "number_printer_factory"), and should return text that will be used in place of the object. This can be used to generate Markdown links, or do other useful things. By default, a bullet point followed by the name of the attribute will be provided, for example "* position".	None

Returns:

Type	Description
Callable[[str, Optional[str]], str]	A Transdoc rule function that filters the list of attributes using filter and formats the list of attributes using formatter.

transdoc.rules.python_object_attributes = python_object_attributes_rule_gen() module-attribute

Generate a list of attributes for an object.

This imports the object from the given module before determining its attributes.

Parameters:

Name	Type	Description	Default
module	str	Module name to import object from.	required
object	str	Object to list attributes from. If not provided, attributes are listed from module instead. Defaults to None.	required