README.rst

Sphinx Contrib Session

Table of contents

• Setting Up
• Example
• Syntax
  • Supported Session Types
• Examples

Setting Up

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

# 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

.. session:: pycon

   >>> h = 'hello'
   >>> print('hello')
   hello
   >>> for i in hello:
   ...     print(i)
   h
   e
   l
   l
   o
   >>>

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

.. rst:directive:: .. session:: [language]

   Example::

      .. session:: ruby

         Some Ruby code.

   This directive takes a language name as an argument.

   .. rubric:: options

   .. rst:directive:option:: linenos
      :type: no value

      Enable to generate line numbers for the code block::

         .. session:: ruby
            :linenos:

            Some more Ruby code.

   .. rst:directive:option:: lineno-start: number
      :type: 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.

   .. rst:directive:option:: emphasize-lines: line numbers
      :type: 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.'


   .. rst:directive:option: force
      :type: no value

      Ignore minor errors on highlighting

   .. rst:directive:option:: caption: caption of code block
      :type: text

      Set a caption to the code block.

   .. rst:directive:option:: name: a label for hyperlink
      :type: text

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

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

           >>> print 'Explicit is better than implicit.'
           Explicit is better than implicit.

   .. rst:directive:option:: dedent: number
      :type: number

      Strip indentation characters from the code block. For example::

         .. session:: ruby
            :dedent: 4

                some ruby code

   .. rst:directive:option:: force
      :type: 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:

• BashSessionLexer https://pygments.org/docs/lexers/#pygments.lexers.shell.BashSessionLexer - also known as console and shell-session.
• MSDOSSessionLexer https://pygments.org/docs/lexers/#pygments.lexers.shell.MSDOSSessionLexer - also known as doscon.
• PowerShellSessionLexer https://pygments.org/docs/lexers/#pygments.lexers.shell.PowerShellSessionLexer - also known as ps1con.
• TcshSessionLexer https://pygments.org/docs/lexers/#pygments.lexers.shell.TcshSessionLexer - also known as tcshcon
• https://pygments.org/docs/lexers/#pygments.lexers.python.PythonConsoleLexer
• https://pygments.org/docs/lexers/#pygments.lexers.r.RConsoleLexer
• https://pygments.org/docs/lexers/#pygments.lexers.sql.PostgresConsoleLexer
• https://pygments.org/docs/lexers/#pygments.lexers.sql.SqliteConsoleLexer
• https://pygments.org/docs/lexers/#pygments.lexers.ruby.RubyConsoleLexer

Lexers are wanted for;

• GDB debugging session.
• TCL script session.

Examples

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