Sphinx extensions¶

Setup¶

Once Click Extra is installed, you can enable its extensions in your Sphinx’s conf.py:

extensions = [
    ...
    "click_extra.sphinx",
]

click directives¶

Click Extra adds two new directives:

• click:example to display any Click-based Python code blocks in Sphinx

• click:run to invoke the CLI defined above, and display the results as if was executed in a terminmal

Thanks to these, you can directly demonstrate the usage of your CLI in your documentation. You no longer have to maintain screenshots of you CLIs. Or copy and paste their outputs to keep them in sync with the latest revision. Click Extra will do that job for you.

These directives supports both MyST Markdown and reStructuredText syntax.

Usage¶

Here is how to define a simple Click-based CLI with the click:example directive:

```{click:example}
from click_extra import echo, extra_command, option, style

@extra_command
@option("--name", prompt="Your name", help="The person to greet.")
def hello_world(name):
    """Simple program that greets NAME."""
    echo(f"Hello, {style(name, fg='red')}!")
```

.. click:example::

    from click_extra import echo, extra_command, option, style

    @extra_command
    @option("--name", prompt="Your name", help="The person to greet.")
    def hello_world(name):
        """Simple program that greets NAME."""
        echo(f"Hello, {style(name, fg='red')}!")

After defining the CLI source code in the click:example directive above, you can invoke it with the click:run directive.

The click:run directive expects a Python code block that uses the invoke function. This function is specifically designed to run Click-based CLIs and handle their execution and output.

Here is how we invoke our example with a --help option:

```{click:run}
invoke(hello_world, args=["--help"])
```

.. click:run::

    invoke(hello_world, args=["--help"])

Placed in your Sphinx documentation, the two blocks above renders to:

from click_extra import echo, extra_command, option, style

@extra_command
@option("--name", prompt="Your name", help="The person to greet.")
def hello_world(name):
    """Simple program that greets NAME."""
    echo(f"Hello, {style(name, fg='red')}!")

$ hello-world --help
Usage: hello-world [OPTIONS]

  Simple program that greets NAME.

Options:
  --name TEXT               The person to greet.
  --time / --no-time        Measure and print elapsed execution time.  [default:
                            no-time]
  --color, --ansi / --no-color, --no-ansi
                            Strip out all colors and all ANSI codes from output.
                            [default: color]
  -C, --config CONFIG_PATH  Location of the configuration file. Supports glob
                            pattern of local path and remote URL.  [default:
                            ~/.config/hello-
                            world/*.{toml,yaml,yml,json,ini,xml}]
  --show-params             Show all CLI parameters, their provenance, defaults
                            and value, then exit.
  --verbosity LEVEL         Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                            [default: WARNING]
  -v, --verbose             Increase the default WARNING verbosity by one level
                            for each additional repetition of the option.
                            [default: 0]
  --version                 Show the version and exit.
  -h, --help                Show this message and exit.

This is perfect for documentation, as it shows both the source code of the CLI and its results.

Notice how the CLI code is properly rendered as a Python code block with syntax highlighting. And how the invocation of that CLI renders into a terminal session with ANSI coloring of output.

You can then invoke that CLI again with its --name option:

```{click:run}
invoke(hello_world, args=["--name", "Joe"])
```

.. click:run::

    invoke(hello_world, args=["--name", "Joe"])

Which renders in Sphinx like it was executed in a terminal block:

$ hello-world --name Joe
Hello, Joe!

Options¶

You can pass options to both the click:example and click:run directives to customize their behavior:

```{click:example}
:caption: A magnificent ✨ Hello World CLI!
:linenos:
:emphasize-lines: 4,7
from click_extra import echo, extra_command, option, style

@extra_command
@option("--name", prompt="Your name", help="The person to greet.")
def hello_world(name):
    """Simple program that greets NAME."""
    echo(f"Hello, {style(name, fg='red')}!")
```

.. click:example::
   :caption: A magnificent ✨ Hello World CLI!
   :linenos:
   :emphasize-lines: 4,7

   from click_extra import echo, extra_command, option, style

   @extra_command
   @option("--name", prompt="Your name", help="The person to greet.")
   def hello_world(name):
       """Simple program that greets NAME."""
       echo(f"Hello, {style(name, fg='red')}!")

1from click_extra import echo, extra_command, option, style
2
3@extra_command
4@option("--name", prompt="Your name", help="The person to greet.")
5def hello_world(name):
6    """Simple program that greets NAME."""
7    echo(f"Hello, {style(name, fg='red')}!")

```{click:example}
:hide-source:
from click_extra import echo, extra_command, style

@extra_command
def simple_print():
    echo(f"Just a {style('string', fg='blue')} to print.")
```

```{click:run}
invoke(simple_print)
```

.. click:example::
   :hide-source:

   from click_extra import echo, extra_command, style

   @extra_command
   def simple_print():
       echo(f"Just a {style('string', fg='blue')} to print.")

.. click:run::

   invoke(simple_print)

$ simple-print
Just a string to print.

```{click:run}
:show-source:
result = invoke(simple_print)

# Some inline tests.
assert result.exit_code == 0, "CLI execution failed"
assert not result.stderr, "Found error messages in <stderr>"
```

.. click:run::
   :show-source:

   result = invoke(simple_print)

   # Some inline tests.
   assert result.exit_code == 0, "CLI execution failed"
   assert not result.stderr, "Found error messages in <stderr>"

result = invoke(simple_print)

# Some inline tests.
assert result.exit_code == 0, "CLI execution failed"
assert not result.stderr, "Found error messages in <stderr>"

$ simple-print
Just a string to print.

Inline tests¶

The click:run directive can also be used to embed tests in your documentation.

You can write tests in your documentation, and they will be executed at build time. This allows you to catch regressions early, and ensure that your documentation is always up-to-date with the latest version of your CLI, in the spirit of doctest and Docs as Tests.

For example, here is a simple CLI:

```{click:example}
from click import echo, command

@command
def yo_cli():
    echo("Yo!")
```

.. click:example::

   from click import echo, command

   @command
   def yo_cli():
       echo("Yo!")

Let’s put the code above in a click:example directive. And then put the following Python code into a click:run block:

```{click:run}
result = invoke(yo_cli, args=["--help"])

assert result.exit_code == 0, "CLI execution failed"
assert not result.stderr, "Found error messages in <stderr>"
assert "Usage: yo-cli [OPTIONS]" in result.stdout, "Usage line not found in help screen"
```

.. click:run::

   result = invoke(yo_cli, args=["--help"])

   assert result.exit_code == 0, "CLI execution failed"
   assert not result.stderr, "Found error messages in <stderr>"
   assert "Usage: yo-cli [OPTIONS]" in result.stdout, "Usage line not found in help screen"

See how we collect here the result of the invoke command, and separately inspect the exit_code, stderr and stdout of with assert statements.

If for any reason our CLI changes and its help screen is no longer what we expect, the test will fail and the documentation build will break with a message similar to:

Versions
========

* Platform:         darwin; (macOS-15.5-arm64-64bit)
* Python version:   3.11.11 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.21.2
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Loaded Extensions
=================

(...)
* myst_parser (4.0.1)
* click_extra.sphinx (5.1.0)

Traceback
=========

      File "(...)/click-extra/docs/sphinx.md:197", line 5, in <module>
    AssertionError: Usage line not found in help screen

The full traceback has been saved in:
/var/folders/gr/1frk79j52flczzs2rrpfnkl80000gn/T/sphinx-err-5l6axu9g.log

Having your build fails when something unexpected happens is a great signal to catch regressions early.

On the other hand, if the build succeed, the click:run block will render as usual with the result of the invocation:

$ yo-cli --help
Usage: yo-cli [OPTIONS]

Options:
  --help  Show this message and exit.

ANSI shell sessions¶

Sphinx extensions from Click Extra automaticcaly integrates the new ANSI-capable lexers for Pygments.

This allows you to render colored shell sessions in code blocks by referring to the ansi- prefixed lexers:

```{code-block} ansi-shell-session
$ # Print ANSI foreground colors.
$ for i in {0..255}; do \
>     printf '\e[38;5;%dm%3d ' $i $i \
>     (((i+3) % 18)) || printf '\e[0m\n' \
> done
  0   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15 
 16  17  18  19  20  21  22  23  24  25  26  27  28  29  30  31  32  33 
 34  35  36  37  38  39  40  41  42  43  44  45  46  47  48  49  50  51 
 52  53  54  55  56  57  58  59  60  61  62  63  64  65  66  67  68  69 
 70  71  72  73  74  75  76  77  78  79  80  81  82  83  84  85  86  87 
 88  89  90  91  92  93  94  95  96  97  98  99 100 101 102 103 104 105 
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 
250 251 252 253 254 255
```

.. code-block:: ansi-shell-session

    $ # Print ANSI foreground colors.
    $ for i in {0..255}; do \
    >     printf '\e[38;5;%dm%3d ' $i $i \
    >     (((i+3) % 18)) || printf '\e[0m\n' \
    > done
      0   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15 
     16  17  18  19  20  21  22  23  24  25  26  27  28  29  30  31  32  33 
     34  35  36  37  38  39  40  41  42  43  44  45  46  47  48  49  50  51 
     52  53  54  55  56  57  58  59  60  61  62  63  64  65  66  67  68  69 
     70  71  72  73  74  75  76  77  78  79  80  81  82  83  84  85  86  87 
     88  89  90  91  92  93  94  95  96  97  98  99 100 101 102 103 104 105 
    106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 
    124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 
    142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 
    160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 
    178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 
    196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 
    214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 
    232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 
    250 251 252 253 254 255

In Sphinx, the snippet above renders to:

$ # Print ANSI foreground colors.
$ for i in {0..255}; do \
>     printf '\e[38;5;%dm%3d ' $i $i \
>     (((i+3) % 18)) || printf '\e[0m\n' \
> done
  0   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15 
 16  17  18  19  20  21  22  23  24  25  26  27  28  29  30  31  32  33 
 34  35  36  37  38  39  40  41  42  43  44  45  46  47  48  49  50  51 
 52  53  54  55  56  57  58  59  60  61  62  63  64  65  66  67  68  69 
 70  71  72  73  74  75  76  77  78  79  80  81  82  83  84  85  86  87 
 88  89  90  91  92  93  94  95  96  97  98  99 100 101 102 103 104 105 
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 
124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 
160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 
250 251 252 253 254 255

Legacy mixed syntax: MyST + reStructuredText¶

Before MyST was fully integrated into Sphinx, many projects used a mixed syntax setup with MyST and reStructuredText. If you are maintaining such a project or need to ensure compatibility with older documentation, you can use these legacy Sphinx snippets.

This rely on MyST’s ability to embed reStructuredText within MyST documents, via the {eval-rst} directive.

So instead of using the {click:example} and {click:run} MyST directive, you can wrap your reStructuredText code blocks with {eval-rst}:

```{eval-rst}
.. click:example::

   from click import echo, command

   @command
   def yo_cli():
       echo("Yo!")

.. click:run::

    invoke(yo_cli)
```

Which renders to:

from click import echo, command

@command
def yo_cli():
    echo("Yo!")

$ yo-cli
Yo!

  File ".../click-extra/docs/sphinx.md:372", line 1, in <module>
NameError: name 'yo_cli' is not defined

Syntax highlight language¶

By default, code blocks produced by the directives are automatically highlighted with these languages:

• click:example: python

• click:run: ansi-shell-session

If for any reason you want to override these defaults, you can pass the language as an optional parameter to the directive.

Let’s say you have a CLI that is only printing SQL queries in its output:

from click_extra import echo, extra_command, option

@extra_command
@option("--name")
def sql_output(name):
    sql_query = f"SELECT * FROM users WHERE name = '{name}';"
    echo(sql_query)

Then you can force the SQL Pygments highlighter on its output by passing the short name of that lexer (i.e. sql) as the first argument to the directive:

```{click:run} sql
invoke(sql_output, args=["--name", "Joe"])
```

And renders to:

$ sql-output --name Joe
SELECT * FROM users WHERE name = 'Joe';

See how the output (i.e. the second line above) is now rendered with the sql Pygments lexer, which is more appropriate for SQL queries. But of course it also parse and renders the whole block as if it is SQL code, which mess up the rendering of the first line, as it is a shell command.

In fact, if you look at Sphinx logs, you will see that a warning has been raised because of that:

.../docs/sphinx.md:257: WARNING: Lexing literal_block "$ sql-output --name Joe\nSELECT * FROM users WHERE name = 'Joe';" as "sql" resulted in an error at token: '$'. Retrying in relaxed mode. [misc.highlighting_failure]

click_extra.sphinx API¶

        classDiagram
  ClickDirective <|-- DeclareExampleDirective
  ClickDirective <|-- RunExampleDirective
  Domain <|-- ClickDomain
  EchoingStdin <|-- EofEchoingStdin
  ExtraCliRunner <|-- ExampleRunner
  SphinxDirective <|-- ClickDirective
    

Helpers and utilities for Sphinx rendering of CLI based on Click Extra.

click_extra.sphinx.RST_INDENT = '   '¶

The indentation used for rST code blocks lines.

class click_extra.sphinx.EofEchoingStdin(input, output)[source]¶

Bases: EchoingStdin

Like click.testing.EchoingStdin but adds a visible ^D in place of the EOT character ().

ExampleRunner.invoke() adds  when terminate_input=True.

click_extra.sphinx.patch_modules()[source]¶

Patch modules to work better with ExampleRunner.invoke().

subprocess.call` output is redirected to ``click.echo so it shows up in the example output.

class click_extra.sphinx.ExampleRunner[source]¶

Bases: ExtraCliRunner

click.testing.CliRunner with additional features.

This class inherits from click_extra.testing.ExtraCliRunner to have full control of contextual color settings by the way of the color parameter. It also produce unfiltered ANSI codes so that the Directive sub-classes below can render colors in the HTML output.

force_color: bool = True¶

Force color rendering in invoke calls.

isolation(*args, **kwargs)[source]¶

A context manager that sets up the isolation for invoking of a command line tool. This sets up <stdin> with the given input data and os.environ with the overrides from the given dictionary. This also rebinds some internals in Click to be mocked (like the prompt functionality).

This is automatically done in the invoke() method.

Parameters:

• input – the input stream to put into sys.stdin.

• env – the environment overrides as dictionary.

• color – whether the output should contain color codes. The application can still override this explicitly.

Added in version 8.2: An additional output stream is returned, which is a mix of <stdout> and <stderr> streams.

Changed in version 8.2: Always returns the <stderr> stream.

Changed in version 8.0: <stderr> is opened with errors="backslashreplace" instead of the default "strict".

Changed in version 4.0: Added the color parameter.

invoke(cli, args=None, prog_name=None, input=None, terminate_input=False, env=None, _output_lines=None, **extra)[source]¶

Like CliRunner.invoke() but displays what the user would enter in the terminal for env vars, command arguments, and prompts.

Parameters:

• terminate_input – Whether to display ^D after a list of input.

• _output_lines – A list used internally to collect lines to be displayed.

Return type:

Result

declare_example(source_code, location)[source]¶

Execute the given code, adding it to the runner’s namespace.

Return type:

None

run_example(source_code, location)[source]¶

Run commands by executing the given code, returning the lines of input and output. The code should be a series of the following functions:

• invoke(): Invoke a command, adding env vars, input, and output to the output.

• isolated_filesystem(): A context manager that changes to a temporary directory while executing the block.

Return type:

list[str]

env: cabc.Mapping[str, str | None]¶

class click_extra.sphinx.ClickDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

has_content = True¶

May the directive have content?

required_arguments = 0¶

Number of required directive arguments.

optional_arguments = 1¶

The optional argument overrides the default Pygments language to use.

final_argument_whitespace = False¶

May the final argument contain whitespace?

option_spec: ClassVar[dict[str, Callable[[str], Any]]] = {'caption': <function unchanged_required>, 'class': <function class_option>, 'dedent': <function optional_int>, 'emphasize-lines': <function unchanged_required>, 'force': <function flag>, 'hide-results': <function flag>, 'hide-source': <function flag>, 'language': <function unchanged_required>, 'lineno-start': <class 'int'>, 'linenos': <function flag>, 'name': <function unchanged>, 'show-results': <function flag>, 'show-source': <function flag>}¶

Options supported by this directive.

Support the same options as sphinx.directives.code.CodeBlock, and some specific to Click directives.

default_language: str¶

Default highlighting language to use to render the code block.

All Pygments’ languages short names are recognized.

default_show_source: bool = True¶

Whether to render the source code of the example in the code block.

default_show_results: bool = True¶

Whether to render the results of the example in the code block.

runner_func_id: str¶

The name of the function to call on the ExampleRunner instance.

property runner: ExampleRunner¶

Get or create the ExampleRunner instance associated with a document.

Creates one runner per document.

property language: str¶

Short name of the Pygments lexer used to highlight the code block.

Returns, in order of precedence, the language specified in the :language: directive options, the first argument of the directive (if any), or the default set in the directive class.

property code_block_options: list[str]¶

Render the options supported by Sphinx’ native code-block directive.

property show_source: bool¶

Whether to show the source code of the example in the code block.

The last occurrence of either show-source or hide-source options wins. If neither is set, the default is taken from default_show_source.

property show_results: bool¶

Whether to show the results of running the example in the code block.

The last occurrence of either show-results or hide-results options wins. If neither is set, the default is taken from default_show_results.

property is_myst_syntax: bool¶

Check if the current directive is written with MyST syntax.

render_code_block(lines, language)[source]¶

Render the code block with the source code and results.

Return type:

list[str]

run()[source]¶

Return type:

list[Node]

class click_extra.sphinx.DeclareExampleDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: ClickDirective

Directive to declare a Click CLI example.

This directive is used to declare a Click CLI example in the documentation. It renders the source code of the example in a Python code block.

default_language: str = 'python'¶

Default highlighting language to use to render the code block.

All Pygments’ languages short names are recognized.

default_show_source: bool = True¶

Whether to render the source code of the example in the code block.

default_show_results: bool = False¶

Whether to render the results of the example in the code block.

runner_func_id: str = 'declare_example'¶

The name of the function to call on the ExampleRunner instance.

class click_extra.sphinx.RunExampleDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: ClickDirective

Directive to run a Click CLI example.

This directive is used to run a Click CLI example in the documentation. It renders the results of running the example in a shell session code block supporting ANSI colors.

default_language: str = 'ansi-shell-session'¶

Default highlighting language to use to render the code block.

All Pygments’ languages short names are recognized.

default_show_source: bool = False¶

Whether to render the source code of the example in the code block.

default_show_results: bool = True¶

Whether to render the results of the example in the code block.

runner_func_id: str = 'run_example'¶

The name of the function to call on the ExampleRunner instance.

class click_extra.sphinx.ClickDomain(env)[source]¶

Bases: Domain

Setup new directives under the same click namespace:

• click:example which renders a Click CLI source code

• click:run which renders the results of running a Click CLI

data: dict[str, Any]¶

data value

env: BuildEnvironment¶

name = 'click'¶

domain name: should be short, but unique

label = 'Click'¶

domain label: longer, more descriptive (used in messages)

directives: dict[str, type[Directive]] = {'example': <class 'click_extra.sphinx.DeclareExampleDirective'>, 'run': <class 'click_extra.sphinx.RunExampleDirective'>}¶

directive name -> directive class

click_extra.sphinx.delete_example_runner_state(app, doctree)[source]¶

Close and remove the ExampleRunner instance once the document has been read.

Return type:

None

click_extra.sphinx.setup(app)[source]¶

Register new directives, augmented with ANSI coloring.

Caution

This function forces the Sphinx app to use sphinx.highlighting.PygmentsBridge instead of the default HTML formatter to add support for ANSI colors in code blocks.

Return type:

ExtensionMetadata