epkg#

This role can be used to store urls in the configuration file and only show the anchor in the documentation.

Usage#

In conf.py:

extensions = [ ...
    'sphinx_runpython.epkg',
]

epkg_dictionary = {
    'pandoc': 'http://johnmacfarlane.net/pandoc/',                                       # 1
    'pandas': ('http://pandas.pydata.org/pandas-docs/stable/',                           # 2
        ('http://pandas.pydata.org/pandas-docs/stable/generated/pandas.{0}.html', 1)),   # 3
    }

The variable epkg_dictionary stores the list of url to display. It can be a simple string or a list of possibililies with multiple parameters. The three options above can used like this. The last one allows one parameter separated by :.

The last link is broken before the current file is not python file but a rst. The file extension must be specified. For some websites, url and functions do not follow the same rule. A function must be used in this case to handle the mapping.

def weird_mapping(input):
    # The function receives whatever is between `...`.
    ...
    return anchor, url

This function must be placed at the end or be the only available option.

epkg_dictionary = { 'weird_site': weird_mapping }

However, because it is impossible to use a function as a value in the configuration because pickle does not handle this scenario (see PicklingError on environment when config option value is a callable), my_custom_links needs to be replaced by: ("module_where_it_is_defined.my_custom_links", None). The role epkg will import it based on its name.

Directive#

sphinx_runpython.epkg.sphinx_epkg_extension.epkg_role(role, rawtext, text, lineno, inliner, options=None, content=None)[source]#

Defines custom role epkg. A list of supported urls must be defined in the configuration file. It wants to replace something like:

`to_html <https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_html.html>`_

By:

:epkg:`pandas:DataFrame.to_html`

It inserts in the configuration the variable:

epkg_dictionary = {
    'pandas': (
        'http://pandas.pydata.org/pandas-docs/stable/generated/',
        ('http://pandas.pydata.org/pandas-docs/stable/generated/{0}.html', 1)
    ),
    # 1 for one parameter
    '*py': (
        'https://docs.python.org/3/',
        ('https://docs.python.org/3/library/{0}.html#{0}.{1}', 2)
    ),
}

If the module name starts with a ‘*’, the anchor does not contain it. See also epkg. If no template is found, the role will look into the list of options to see if there is one function. It must be the last one.

def my_custom_links(input):
    return "string to display", "url"

epkg_dictionary = {
    'weird_package': (
        'http://pandas.pydata.org/pandas-docs/stable/generated/',
        ('http://pandas.pydata.org/pandas-docs/stable/generated/{0}.html', 1),
        my_custom_links
    )

However, it is impossible to use a function as a value in the configuration because pickle does not handle this scenario (see PicklingError on environment when config option value is a callable), my_custom_links needs to be replaced by: ("module_where_it_is_defined.function_name", None). The role epkg will import it based on its name.

Parameters:

  • role – The role name used in the document.

  • rawtext – The entire markup snippet, with role.

  • text – The text marked with the role.

  • lineno – The line number where rawtext appears in the input.

  • inliner – The inliner instance that called us.

  • options – Directive options for customization.

  • content – The directive content for customization.