Directives

.. typer::

.. typer:: import.path.to.module:main
  :prog: script_name
  :make-sections:
  :show-nested:
  :markup-mode: markdown
  :width: 65
  :preferred: html
  :builders: html=html,svg,text:latex=svg,text:text=text
  :iframe-height: 600
  :convert-png: html|latex
  :theme: light
  :console-kwargs: import.path.to.console_kwargs
  :svg-kwargs: import.path.to.svg_kwargs
  :html-kwargs: import.path.to.html_kwargs
  :text-kwargs: import.path.to.text_kwargs

The only required parameter is the first argument. This is an import path to the Typer or Click application to render. It may also include nested subcommands and may be delimited by either ., : or :: characters. For example, to render a subcommand called print from another subcommand called add in a Typer app named app in a module called command in a package called mypackage:

.. typer:: mypackage.command.app:add:print

:prog: program cli name (text)

The script invocation name to use in the rendered help text. This parameter is optional, the directive will attempt to infer the name but this is not always possible to do reliably solely from the source code. If the name cannot be inferred, this parameter should be supplied.

:make-sections: (flag)

This is a flag parameter. If set, the directive will generate hierarchical sections for each command.

:show-nested: (flag)

This is a flag parameter. If set, the directive will include all subcommands in the command tree.

:markup-mode: (text)

Override the Typer rich_markup_mode command configuration value. Supports either markdown or rich. See the Typer docs.

:width: (integer)

default: 65

The width of the terminal window to use when rendering the help through rich. 65 is a good value for text or html renderings on the read the docs theme

:preferred: (text)

The preferred render format. Either html, svg or text. If not supplied the render format will be inferred from the builder’s priority supported format list. You can replace the default priority lists with the builders parameter. The default format for the html and latex builders is svg.

:builders: (text - a colon delimited list of mappings from builder name to priority ordered csv of supported formats.)

default: html=html,svg,text:latex=svg,text:text=text

Override the default builder priority render format lists. For example the preset is equivalent to:

html=html,svg,text:latex=svg,text:text=text

This parameter can be helpful if you’re rendering your docs with multiple builders and do not want the preset formats.

:iframe-height: (integer)

default: 600

The height of the iframe to use when rendering to html. When html rendering is embedded in an html page an iframe is used. The height of the iframe can be set with this parameter. Alternatively, the height of the iframe can be dynamically determined if selenium is installed. See also iframe height cache.

:convert-png: (text - a delimited list of builders)

Convert the rendered help to a png file for this delimited list of builders. The delimiter can be any character. For example:

.. typer:: import.path.to.module:main
  :convert-png: html|latex

All formats, html, text and svg can be converted to png. For some builders, namely pdf the html and svg formats may require non standard fonts to be installed or otherwise render unpredictably. The png format is a good alternative for these builders.

:theme: (text)

default: light

A named rich terminal theme to use when rendering the help in either html or svg formats. Supported themes:

• light

• dark

• monokai

• dimmed_monokai

• night_owlish

• red_sands

• blue_waves

:console-kwargs: (text)

A python import path to a dictionary or callable returning a dictionary containing parameters to pass to the rich console before output rendering. The defaults are those defined by the Typer library. See rich.console.Console.

:svg-kwargs: (text)

A python import path to a dictionary or callable returning a dictionary containing parameters to pass to the rich console export_svg function. See rich.console.Console.export_svg().

:html-kwargs: (text)

A python import path to a dictionary or callable returning a dictionary containing parameters to pass to the rich console export_html function. See rich.console.Console.export_html().

:text-kwargs: (text)

A python import path to a dictionary or callable returning a dictionary containing parameters to pass to the rich console export_text function. See rich.console.Console.export_text().