Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to show and hide code in sphinx doc?

I want the same functionality mention in Sphinx, reStructuredText show/hide code snippets. But there is no code shared on that post.

like image 878
Nilesh Avatar asked Nov 16 '11 12:11

Nilesh


People also ask

What is Toctree Sphinx?

.. toctree is a Sphinx-defined directive in which you explicitly list documents whose TOCs will be listed out.


1 Answers

SQLAlchemy docs

The SQLAlchemy documentation uses a special extension (https://bitbucket.org/zzzeek/zzzeeksphinx/).

The documentation source contains markup with custom options and tokens, like in this example:

.. sourcecode:: python+sql
 
    {sql}>>> engine.execute("select 1").scalar()
    select 1
    ()
    {stop}1

This is processed by a special Pygments lexer (PythonWithSQLLexer) and Pygments formatter (PopupSQLFormatter) in order to generate a "popup" <div> with the code snippet and the link that shows/hides it. The source code is in sqlformatter.py.

The show/hide toggling is handled by jQuery magic in init.js.

The Mako templating system is used to generate the HTML pages (the default templating system in Sphinx is Jinja). This is configured by subclassing TemplateBridge in mako.py.

In the template file layout.mako, the paths to CSS and JavaScript files (including init.js) are specified. For more on Sphinx templating, see http://sphinx-doc.org/templating.html.

Python docs

Many code examples in the Python documentation feature a "button" that toggles display of interactive prompts (>>>, ...) and output in doctest-style code snippets. With prompts and output out of the way, the code can be more easily copied and pasted. Here are several examples: http://docs.python.org/library/datetime.html#module-datetime.

The feature is implemented in copybutton.js.

like image 79
mzjn Avatar answered Sep 29 '22 12:09

mzjn