lib.roles.common

Core parts for Django Docutils roles.

django_docutils.lib.roles.common.generic_url_role(name, text, url_handler_fn, innernodeclass=<class 'docutils.nodes.Text'>)[source]

Docutils Role for Django Docutils.

This generic role also handles explicit titles (:role:`yata yata <target>`)

This breaks convention a feels a bit jenky at first. It uses a callback because figuring out the url is the only magic that happens, but its sandwiched in the middle.

Parameters:

  • name (name of the role, e.g. 'github') –

  • text (text inside of the role, e.g:) –

    • ‘airline-mode/airline-mode’

    • ’this repo <airline-mode/airline-mode>’

  • url_handler_fn (django_docutils.lib.roles.types.UrlHandlerFn) – a function that accepts the target param

Return type:

django_docutils.lib.roles.types.RoleFnReturnValue

Examples

def github_role(
    name, rawtext, text, lineno, inliner, options={}, content=[]
):
    def url_handler(target):
        return 'https://github.com/{}'.format(target)

    return generic_url_role(name, text, url_handler)

roles.register_local_role('gh', github_role)
django_docutils.lib.roles.common.generic_remote_url_role(name, text, url_handler_fn, innernodeclass=<class 'docutils.nodes.Text'>)[source]

Docutils Role that can call an external data source for title and URL.

Same as generic_url_role, but can return url and title via external data source.

The url_handler_fn returns a title and a url.

In cases like Amazon API, database lookups, and other stuff, information may be looked up by key, and we may get a fresh title to fill in if nothing else explicit is mentioned.

Parameters:

  • name (name of the role, e.g. 'github') –

  • text (text inside of the role, e.g:) –

    • ‘airline-mode/airline-mode’

    • ’this repo <airline-mode/airline-mode>’

  • url_handler_fn (django_docutils.lib.roles.types.RemoteUrlHandlerFn) – a function that accepts the target param, example:

Return type:

django_docutils.lib.roles.types.RoleFnReturnValue

Examples

Simple example, let’s create a role:

def amzn_role(
    name, rawtext, text, lineno, inliner, options={}, content=[]
):
    def url_handler(target):
        query = amzn.lookup(ItemId=target)
        return query.title, query.offer_url

    return generic_remote_url_role(name, text, url_handler)

roles.register_local_role('amzn', amzn_role)