Showing source code examples in Sphinx¶
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
::
SELECT * FROM mytable
.. 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:
The following is a SQL statement.
.. code-block:: sql
:linenos:
SELECT * FROM mytable
Line numbers are useful for long blocks such as this one:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | -- http://www.postgresonline.com/journal/index.php?/archives/97-SQL-Coding-Standards-To-Each-His-Own-Part-II.html
SELECT persons.id, persons.first_name, persons.last_name, forums.category,
COUNT(DISTINCT posts.id) as num_posts,
COALESCE(MAX(comments.rating), 0) AS highest_rating,
COALESCE(MIN(comments.rating), 0) AS lowest_rating
FROM persons JOIN posts ON persons.id = posts.author
JOIN forums on posts.forum = forums.id
LEFT OUTER JOIN comments ON posts.id = comments.post
WHERE persons.status > 0
AND forums.ratings = TRUE
AND comments.post_date > ( now() - INTERVAL '1 year')
GROUP BY persons.id, persons.first_name, persons.last_name, forums.category
HAVING count(DISTINCT posts.id) > 0
ORDER BY persons.last_name, persons.first_name;
|
Literalinclude directive¶
Another option is to include part of a given source code file, like this:
.. literalinclude:: filename
:linenos:
:language:
:lines:
:start-after:
:end-before:
:emphasize-lines:
Just below is a example:
Literalinclude directive
************************
Another option is to include part of a given source code file, like this::
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 (if installed): 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 4 and XHTML 1 | html |
XML | xml |
XSLT | xslt |
XQuery | xquery |
JavaScript | javascript |
JSON data structures | json |
PHP source code | php |
PHP embedded in HTML | html+php |
Python 2 | python |
Python 2 tracebacks | pytb |
Python console | pycon |
Java | java |
Configuration file in the Java’s properties format | jproperties |
Configuration file in the Apache config file format | apacheconf |
R source code (or S, or S-plus) | r |
R console | rout |
Matlab | matlab |
Matlab sessions | matlabsession |
NumPy | numpy |