Showing source code

Literal blocks

Standard reST literal blocks are started by :: at the end of the preceding paragraph and delimited by indentation.

Highlight directive

The default highlighting language is Python: it can be be changed using the highlight directive within a document:

.. highlight:: html

The literal blocks are now highlighted as HTML, until a new directive is found.

<html><head></head>
<body>This is a text.</body>
</html>

The following directive changes the hightlight language to SQL.:

.. highlight:: sql

Therefore, the following block is highlighted as SQL.

SELECT * FROM mytable

If we want to stop highlighting, we can use the none language, which is a special lexer that does not do any highlighting.:

.. highlight:: none

From here on no highlighting will be done.

SELECT * FROM mytable

Code-block directive

The code-block directive can be used to declare the specific language to be used in a block, regardless of the highlighting language. Use the following directive:

.. code-block:: sql
   :linenos:

   SELECT * FROM mytable

… to create the following result:

1SELECT * FROM mytable

Line numbers are useful for long blocks such as this one:

 1-- http://www.postgresonline.com/journal/index.php?/archives/97-SQL-Coding-Standards-To-Each-His-Own-Part-II.html
 2SELECT persons.id, persons.first_name, persons.last_name, forums.category,
 3   COUNT(DISTINCT posts.id) as num_posts,
 4   COALESCE(MAX(comments.rating), 0) AS highest_rating,
 5   COALESCE(MIN(comments.rating), 0) AS lowest_rating
 6FROM persons JOIN posts ON persons.id = posts.author
 7   JOIN forums on posts.forum = forums.id
 8   LEFT OUTER JOIN comments ON posts.id = comments.post
 9WHERE persons.status > 0
10   AND forums.ratings = TRUE
11   AND comments.post_date > ( now() - INTERVAL '1 year')
12GROUP BY persons.id, persons.first_name, persons.last_name, forums.category
13HAVING count(DISTINCT posts.id) > 0
14ORDER BY persons.last_name, persons.first_name;

Literalinclude directive

Another option is to include part of a given source code file, using the literalinclude directive:

.. literalinclude:: filename
   :linenos:
   :language:
   :lines:
   :start-after:
   :end-before:
   :emphasize-lines:

Just below is a example of the use of the lines option, which includes only the specified lines of the file.:

      JOIN forums on posts.forum = forums.id
      LEFT OUTER JOIN comments ON posts.id = comments.post
   WHERE persons.status > 0
      AND forums.ratings = TRUE

Instead of using line numbers (which can change), it is possible to use the options :start-after and :end-before: that search the included file for lines containing the specified text. For example:

.. literalinclude:: ShowingCodeExamplesInSphinx.rst
   :language: rst
   :start-after: Instead of using
   :end-before: For example

produces this result:

use the options ``:start-after`` and ``:end-before:``
that search the included file for lines containing the specified text.

Pygments lexers

Syntax highlighting is done by Pygments, a syntax highlighting package written in Python. Any of the Pygments language lexers can be used.

The following table lists some useful lexers (in no particular order).

Lexer

Shortname

Structured Query Language

sql

PostgreSQL dialect of SQL

postgresql

PostgreSQL procedural language

plpgsql

PostgreSQL console sessions

psql

ReStructured Text

rst

TeX and LaTeX

latex

DOS/Windows batch file

bat

Windows PowerShell

powershell

Bash shell scripts

bash

Bash shell sessions

console

Cascading Style Sheets

css

HTML

html

XML

xml

XSLT

xslt

XQuery

xquery

JavaScript

javascript

JSON data structures

json

PHP source code

php

PHP embedded in HTML

html+php

Python

python

Python console

pycon

Java

java

R source code (or S, or S-plus)

r

Matlab

matlab

NumPy

numpy

Links