Sphinx-toggleprompt

Sphinx-toggleprompt adds a button to Python code blocks to toggle >>> prompts and remove output lines. It’s copied from the official Python docs theme.

>>> a = 2
>>> print(a)
2

>>> b = ['wow',
...      'eee']
>>> print(b)
['wow', 'eee']

# It works with IPython too
In [1]: cloud_vars = ['total_clouds', 'low_clouds',
   ...:               'mid_clouds', 'high_clouds']
   ...: 

In [2]: print(sorted(cloud_vars))
['high_clouds', 'low_clouds', 'mid_clouds', 'total_clouds']

In [3]: cloud_vars
Out[3]: ['total_clouds', 'low_clouds', 'mid_clouds', 'high_clouds']

# It works with IPython too
In [4]: cloud_vars = ['total_clouds', 'low_clouds',
   ...:               'mid_clouds', 'high_clouds']
   ...: 

In [5]: print(sorted(cloud_vars))
['high_clouds', 'low_clouds', 'mid_clouds', 'total_clouds']

It only adds itself to Python code which contains prompts.

This is formatted as plain text,
so it doesn't get the toggle button.

msg = 'This is python, but no lines start with >>>'
print(msg)

This extension is heavily based on sphinx-copybutton - thanks!

Installation

sphinx-toggleprompt is available on pypi through pip, or you can alternatively install directly from github.

pip install sphinx-toggleprompt

Usage

Add sphinx-toggleprompt to your sphinx extensions list in conf.py and then build your docs - that’s it.

extensions = [
    ...
    'sphinx_toggleprompt',
    ...
]

Configuration

Offset

You can control the offset of the toggleprompt button from the right-hand side of the code cell in pixels with the toggleprompt_offset_right config value. The default is zero (all the way to the right). Simply add toggleprompt_offset_right to your sphinx conf.py:

# In your sphinx conf.py
# Defaults to 0 if not provided.
toggleprompt_offset_right = 35

Default Hidden/Shown

The toggleprompt_default_hidden config value can be set to "true" (a string), in which case prompts will be hidden by default.

Themes

sphinx-toggleprompt has been tested with the Alabaster theme (sphinx’s default) and with the read the docs theme.

Using with sphinx-copybutton

sphinx-toggleprompt works great with sphinx-copybutton - just simply add both of them to the extensions list in conf.py. Setting toggleprompt_offset_right to a value around 35 stops them from overlapping (will probably vary). There’s an example of this in the doc_copybutton folder.

Changelog

V0.4.0 - 08-apr-2023

• Loosened max sphinx version to v6, up from v5.

• Enabled Python 3.11 in CI tests.

V0.3.1 - 11-dec-2022

• Fixed issue with pypi publishing

V0.3.0 - 11-dec-2022

• Dropped support for sphinx < 4.5.0. This is due to https://github.com/sphinx-doc/sphinx/issues/10291

• Added tests for sphinx 5

• Modified sphinx dependency to be less than v6

V0.2.0 - 14-may-2022

• Added toggleprompt_default_hidden config value to allow setting initial hidden/shown state.

V0.1.1 - 07-may-2022

• Added tests for python 3.6 through 3.8

• Added tests for sphinx 4

• Restricted jinja2 dependency version to fix breaking changes introduced in version 3.1

V0.0.5 - 27-Nov-2020

• Add IPython highlighting support

V0.0.3 - 25-jul-2020

• Make the “>>>” text non-selectable

V0.0.2 - 17-may-2020

• Initial release