Sphinx Contrib Session

Setting Up

In conf.py add 'sphinxcontrib_session' to the list of extensions as shown below (note the underscore);

conf.py
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.githubpages',
    'sphinxcontrib_session',
]

Example

h = 'hello'
print('hello')
for i in hello:
    print(i)

Syntax

The .. session:: directive should be a drop in replacement for the ..  code-block:: directive and support the same set of options.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block

.. session:: [language]

   <statements>

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive:option-code-block-linenos :linenos: is supported but generally doesn’t make much sense. https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive:option-code-block-lineno-start

.. session:: [language]

Example:

.. session:: ruby

   Some Ruby code.

This directive takes a language name as an argument.

options

:linenos: (no value)

Enable to generate line numbers for the code block:

.. session:: ruby
   :linenos:

   Some more Ruby code.
:lineno-start: number (number)

Set the first line number of the code block. If present, linenos option is also automatically activated:

.. session:: ruby
   :lineno-start: 10

   Some more Ruby code, with line numbering starting at 10.
:emphasize-lines: line numbers (comma separated numbers)

Emphasize particular lines of the code block:

.. session:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'
:caption: caption of code block (text)

Set a caption to the code block.

:name: a label for hyperlink (text)

Define implicit target name that can be referenced by using ref. For example:

.. session:: python
   :caption: this.py
   :name: this-py

   >>> print 'Explicit is better than implicit.'
   Explicit is better than implicit.
:dedent: number (number)

Strip indentation characters from the code block. For example:

.. session:: ruby
   :dedent: 4

       some ruby code
:force: (no value)

If given, minor errors on highlighting are ignored.

Supported Session Types

In theory any ‘session’ lexer supported by Pygments should work.

The tested sessions are:

Lexers are wanted for;

  • GDB debugging session.

  • TCL script session.

Examples

See: https://sphinxcontrib-session.rtfd.io/