sphinx-terminal

sphinx-terminal allows you to display terminal input and output in your Sphinx documentation.

Basic usage

To display terminal input and output in your Sphinx document, use the terminal directive, providing input and output as follows:

.. terminal::

    input

    output

Input can span multiple lines, as long as the lines are in the same paragraph. Everything after the first blank line in the directive's body is rendered as output.

The prompt defaults to user@host:~$. To customize this, use the :user:, :host:, and :dir: options.

.. terminal::
    :user: author
    :host: canonical
    :dir: ~/path

    echo 'hello'

    hello

Or, declare the entire prompt with the prompt option. This is useful if you're documenting shells other than Bash, such as PowerShell:

.. terminal::
    :prompt: PS C:\Users\Author>

    Write-Output 'hello'

    hello

To render only the output of a command, include the :output-only: flag in the directive's options.

.. terminal::
    :output-only:

    This is rendered as output.

To enable a copy button for users, include the :copy: flag as a directive option. Only the input can be copied.

.. terminal::
    :copy:

    echo 'hello'

    hello

Similarly, to make the output scrollable, include the :scroll: flag as a directive option.

.. terminal::
    :scroll:

    echo 'hello'

    hello

Project setup

sphinx-terminal is published on PyPI and can be installed with:

pip install sphinx-terminal

After adding sphinx-terminal to your Python project, update Sphinx's conf.py file to include sphinx-terminal as one of its extensions:

extensions = [
    "sphinx_terminal"
]

The copy button functionality depends on sphinx-copybutton. sphinx-terminal automatically adds this extension to your Sphinx project and configures it to copy terminal input and ignore the multiline prompt.

copybutton_selector = "span.copybutton, div:not(.terminal-code) > div.highlight > pre"
copybutton_prompt_text = "> |"
copybutton_prompt_is_regexp = True

Customizing these values in your conf.py file overrides the defaults assigned by sphinx-terminal and may compromise the copy button.

Community and support

You can report any issues or bugs on the project's GitHub repository.

If you're interested in contributing, start with the contribution guide.

sphinx-terminal is covered by the Ubuntu Code of Conduct.

License and copyright

sphinx-terminal is released under the GPL-3.0 license.

© 2025 Canonical Ltd.