====================== Sphinx-toggleprompt ====================== .. image:: https://img.shields.io/pypi/v/sphinx-toggleprompt.svg :target: https://pypi.org/project/sphinx-toggleprompt/ .. image:: https://readthedocs.org/projects/sphinx-toggleprompt/badge/?version=stable :target: https://sphinx-toggleprompt.readthedocs.io/en/stable/?badge=stable :alt: Documentation Status .. image:: https://github.com/jurasofish/sphinx-toggleprompt/workflows/build/badge.svg?branch=master :target: https://github.com/jurasofish/sphinx-toggleprompt/actions .. |br| raw:: html
|br| .. image:: _static/example.gif :width: 500px ``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. .. code-block:: python >>> a = 2 >>> print(a) 2 >>> b = ['wow', ... 'eee'] >>> print(b) ['wow', 'eee'] | .. ipython:: python # It works with IPython too cloud_vars = ['total_clouds', 'low_clouds', 'mid_clouds', 'high_clouds'] print(sorted(cloud_vars)) cloud_vars | .. ipython:: python # It works with IPython too cloud_vars = ['total_clouds', 'low_clouds', 'mid_clouds', 'high_clouds'] print(sorted(cloud_vars)) It only adds itself to Python code which contains prompts. .. code-block:: text This is formatted as plain text, so it doesn't get the toggle button. | .. code-block:: python 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. .. code-block:: bash pip install sphinx-toggleprompt Usage ============ Add ``sphinx-toggleprompt`` to your sphinx extensions list in ``conf.py`` and then build your docs - that's it. .. code-block:: python 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``: .. code-block:: python # 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. .. image:: _static/with_copybutton.png :width: 500px Changelog ================================ V0.5.2 - 07-jan-2024 ----------------------- - Fixed read the docs config issue V0.5.1 - 07-jan-2024 ----------------------- - Correctly bump package version V0.5.0 - 07-jan-2024 ----------------------- - Updated the main javascript code to match `that from the official Python docs theme `_. This is more or less a complete rewrite, and notably no longer relies on jquery. - Support Sphinx 4.5.0 through 8.x (previously was 4.5.0 through 5.x). - Support Python 3.9 through 3.12 (previously was 3.6 through 3.11). 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