Sphinx Prompt

1.10.2 · active · verified Sun Apr 12

Sphinx Prompt is a Sphinx directive that allows developers to add code blocks with unselectable prompts to their documentation. This ensures that readers can easily copy and paste commands without including the prompt characters. The library is actively maintained, with frequent minor releases, and is currently at version 1.10.2.

Warnings

breaking Version 1.9.0 introduced compatibility with Sphinx 8, a major release of Sphinx. Users upgrading to `sphinx-prompt` 1.9.0 or later may encounter incompatibilities if their Sphinx project is built with an older Sphinx version (prior to Sphinx 8).
Fix: Ensure your Sphinx installation is compatible with `sphinx-prompt`. For `sphinx-prompt` 1.9.0+, consider upgrading Sphinx to version 8 or later. For older Sphinx versions, use an earlier `sphinx-prompt` release.
breaking The minimum required Python version for `sphinx-prompt` was updated to Python >= 3.11 in recent releases (specifically, 1.10.x). Earlier versions of `sphinx-prompt` (e.g., 1.8.0) supported Python 3.9.
Fix: Upgrade your Python environment to 3.11 or newer if you wish to use `sphinx-prompt` 1.10.0 or later. Alternatively, pin your `sphinx-prompt` version to an earlier release compatible with your Python version (e.g., `<1.10.0` for Python < 3.11).
gotcha When using the `.. prompt::` directive, if your desired prompt string contains spaces (e.g., `(venv) $`), you cannot use positional arguments to specify it due to reStructuredText parsing limitations. The prompt will be incorrectly split.
Fix: Instead of `.. prompt:: bash (venv) $`, use the `:prompts:` option: `.. prompt:: bash :prompts: (venv) $`
gotcha If you are using `sphinx-prompt` alongside other Sphinx extensions that modify or interact with code blocks (e.g., `sphinx-substitution-extensions`), the order in which extensions are loaded in `conf.py` can be important. Incorrect ordering might lead to unexpected rendering or behavior.
Fix: As a general rule, ensure `sphinx_prompt` is listed *before* other extensions that might preprocess or transform code block content in your `conf.py` file to ensure `sphinx-prompt`'s directive is processed first.

Install

pip install sphinx-prompt Install latest version

Imports

Extension Setup
```
# in conf.py
extensions = [
    'sphinx_prompt',
    # ... other extensions
]
```
sphinx-prompt is enabled by adding 'sphinx_prompt' to the 'extensions' list in your Sphinx project's conf.py file. There is no direct Python import for the directive itself; it's used in reStructuredText.

Quickstart

After installing the library and adding 'sphinx_prompt' to your `conf.py` extensions, you can use the `.. prompt::` directive in your reStructuredText files. You can specify a language (e.g., `python`, `bash`, `powershell`) and a custom prompt. If no prompt is given for a shell language, a default is used (e.g., `$` for bash, `C:\>` for batch, `PS C:\>` for powershell).

# conf.py
extensions = [
    'sphinx_prompt',
]

# my_document.rst

.. prompt:: python

   >>> import sys
   >>> print(sys.version)
   3.11.0 (main, ...)

.. prompt:: bash $

   $ ls -l
   total 0
   -rw-r--r-- 1 user group 0 Jan  1 10:00 myfile.txt

view raw JSON →