Configuration

The following extension scoped configuration parameters are available. These should be added to the Sphinx configuration file. For example, to override the default typer_render_html() function our conf.py might look like:

import html

extensions = [
    'sphinxcontrib.typer',
]

# change the default iframe padding
typer_iframe_height_padding = 20

# redfine the default render_html function
def typer_render_html(
    directive: TyperDirective,
    normal_cmd: str,
    html_page: str
) -> str:
    return f'<iframe srcdoc="{html.escape(html_page)}"></iframe>'

Configuration Attributes

typer_iframe_height_padding
Type:
int
Default:
30

A number of pixels to use for padding html iframes.

typer_render_html
Type:
str | Callable[[TyperDirective, str, str], str]
Default:
"sphinxcontrib.typer.typer_render_html"

A callable function (or import path to a callable function) that returns the html to embed in an html page. Only used if the target format is html. See default implementation typer_render_html().

typer_get_iframe_height
Type:
str | Callable[[TyperDirective, str, str], int]
Default:
"sphinxcontrib.typer.typer_get_iframe_height"

A callable function that determines height of the iframe when rendering html format onto an html page. The function must return an integer containing the iframe height. See the default implementation typer_get_iframe_height().

typer_svg2pdf
Type:
str | Callable[[TyperDirective, str, str], None]
Default:
"sphinxcontrib.typer.typer_svg2pdf"

A callable function to convert svg to pdf. The function must write the converted pdf format to the given path. This is only used for latex/pdf builders. See the default implementation typer_svg2pdf().

typer_convert_png
Type:
str | Callable[[TyperDirective, str, str | Path, int, int], None]
Default:
"sphinxcontrib.typer.typer_convert_png"

A callable function to convert the given format to png. The function must write the converted png format to the given path. This function is used when the builder is listed in the typer:convert-png: parameter. See the default implementation typer_convert_png().

typer_get_web_driver
Type:
str | Callable[[TyperDirective, int, int], ContextManager[WebDriver]]
Default:
"sphinxcontrib.typer.typer_get_web_driver"

A callable function to get a selenium web driver. This function must be a context manager and it must yield a selenium web driver. It is used by other workflows that need access to a webdriver. See the default implementation typer_get_web_driver().

Function Hooks

These functions may all be redefined in conf.py to override default behaviors. Your override functions must conform to these function signatures.

Warning

Sphinx will warn that these functions are not pickleable. This messes up sphinx’s caching but that wont break the doc build. You can either suppress the warning or specify these configuration values as import strings instead.

sphinxcontrib.typer.typer_render_html(directive, normal_cmd, html_page)[source]

The default html rendering function. This function returns the html console output wrapped in an iframe. The height of the iframe is dynamically determined by calling the configured typer_get_iframe_height function.

Parameters:

  • directive (TyperDirective) – The TyperDirective instance

  • normal_cmd (str) – The normalized name of the command. (Subcommands are delimited by :)

  • html_page (str) – The html page rendered by console.export_html

Return type:

str

sphinxcontrib.typer.typer_get_iframe_height(directive, normal_cmd, html_page)[source]

The default iframe height calculation function. The iframe height resolution proceeds as follows:

  1. Return the global iframe-height parameter if one was supplied as a parameter on the directive.

  2. Check for a cached height value.

  3. Attempt to use Selenium to dynamically determine the height of the iframe. Padding will be added from the config.typer_iframe_height_padding configuration value. The resulting height is then cached if that path is not None. If the attempt to use Selenium fails (it is not installed) a warning is issued and a default height of 600 is returned.

Parameters:

  • directive (TyperDirective) – The TyperDirective instance

  • normal_cmd (str) – The normalized name of the command. (Subcommands are delimited by :)

  • html_page (str) – The full html document that will be rendered in the iframe

Return type:

int

sphinxcontrib.typer.typer_svg2pdf(directive, svg_contents, pdf_path)[source]

The default typer_svg2pdf function. This function uses the cairosvg package to convert svg to pdf.

Note

You will likely need to install fonts locally on your machine for the output of these conversions to look correct. The default font used by the svg export from rich is FiraCode.

Parameters:

  • directive (TyperDirective) – The TyperDirective instance

  • svg_contents (str) – The svg contents to convert to pdf

  • pdf_path (str) – The path to write the pdf to

sphinxcontrib.typer.typer_convert_png(directive, rendered, png_path, selenium_width=1920, selenium_height=2048)[source]

The default typer_convert_png function. This function writes a png file to the given path by taking a selenium screen shot. It requires selenium to be installed. To override this function with a custom function see the typer_convert_png configuration parameter.

Parameters:

  • directive (TyperDirective) – The TyperDirective instance

  • rendered (str) – The rendered command help. May be html, svg, or text.

  • png_path (str | Path) – The path to write the png to

  • selenium_width (int) – The width of the selenium window - must be larger than the png to avoid cropping, default auto determine

  • selenium_height (int) – The height of the selenium window - must be larger than the png to avoid cropping, default auto determine

sphinxcontrib.typer.typer_get_web_driver(directive, width=1920, height=2048)[source]

The default get_web_driver function. This function yields a selenium web driver instance. It requires selenium to be installed.

To override this function with a custom function see the typer_get_web_driver configuration parameter.

Note

This must be implemented as a context manager that yields the webdriver instance and cleans it up on exit!

Parameters:

  • directive (TyperDirective) – The TyperDirective instance

  • width (int)

  • height (int)

Return type:

Any