Usage

Example

Here is a minimal example of a Click command that uses sphinx-click.rst_to_ansi_formatter and a reST formatted docstring:

import click
from sphinx_click.rst_to_ansi_formatter import make_rst_to_ansi_formatter

base_url = "https://example.github.io/example/main/"
@click.command(cls=make_rst_to_ansi_formatter(base_url))
def minimal():
    """``minimal-example`` displays a `minimal` example of a Click command that uses
    ``sphinx-click.rst_to_ansi_formatter`` and its method ``make_rst_to_ansi_formatter()``
    to convert this reST formatted docstring to an ANSI formatted string to be displayed
    in a terminal.

    See :doc:`Minimal example <minimal>` for more *information*.

    EXAMPLES
    ========

    Some examples ::

      $ minimal-example
      $ minimal-example --help


    For more information about the minimal example script see :doc:`/history`.
    """
    pass

Notice the line @click.command(cls=make_rst_to_ansi_formatter(base_url)). Without the custom cls value the console help output would look like this (gnome-terminal):

Notice for example, that the two lines in the code block have been wrapped into a single line. This would likely be confusing and difficult to read for a user of your app. Also notice that the links are not substituted by the target URL but rather rendered unprocessed as e.g. :doc:`Minimal example <minimal>`. Not very user-friendly!

However, by using the custom cls value in the code example, the console output becomes:

which is hopefully more user-friendly.

Signature

The signature for make_rst_to_ansi_formatter is:

sphinx_click.rst_to_ansi_formatter.formatter.make_rst_to_ansi_formatter(base_url, colors=None, group=False)

Create a reST to ANSI text formatter class.

Parameters:

base_url (str) – The base url for the documentation page. This will be used to construct URLs for the Sphinx reST :doc: role.
colors (dict[str, dict]) – The colors to use when translating reST formatting codes. If not provided, default colors will be used. The dictionary should have keys “heading”, “url”, and “code” with values that are dictionaries with keys “fg” and “style” that specify the foreground color and style to use. The default value is: { "heading": {"fg": Fore.GREEN, "style": Style.BRIGHT}, "url": {"fg": Fore.CYAN, "style": Style.BRIGHT}, "code": {"fg": Fore.CYAN, "style": Style.DIM}, }. For more information about the “fg” and “style” values, see the colorama documentation.
group (bool) – If True, a click.Group will be returned, otherwise a click.Command will be returned. The default is False.

Return type:

CustomRstToAnsiFormatter

Returns:

Returns a sub class of click.Command that can be used to convert help text from reST to ANSI terminal color encoded text