示例的Python源代码或者交互界面都可以使用标准reST模块实现.在正常段落后面跟着 :: 开始，再加上适当缩进.
交互界面需包含提示及Python代码的输出. 交互界面没有特别的标记. 在最后一行输入或输出之后，不应出现空的提示; 这是一个什么都不做的例子:
>>> 1 + 1
2
>>>
语法高亮显示由 Pygments (如果安装) 优雅的显示:
-
每个源文件都有高亮语言”highlighting language”. 默认是 'python' ，多数文件会高亮显示 Python 代码段, 可以在 :confval:`highlight_language` 配置.
-
有了Python 高亮显示模块, 交互界面会自动识别并且适当强调显示. 一般Python 代码仅在可解析时高亮显示 (使用默认的Python, 但是零散的代码段比如shell命令等代码块将不会像Python一样高亮显示).
-
高亮显示语言也可以通过指令 highlight 改变,如下:
.. highlight:: c
C 语言将会被使用直到下一个 highlight 指令.
-
如果文档需展示不同语言片段, 直接使用 code-block 指令给出高亮语言:
.. code-block:: ruby Some Ruby code.
指令别名也可用于 sourcecode .
- （这里我理解错误，直接设置
- .. code:: c （code指令比较老）并不能高亮，前面还必须设置：
- .. highlight:: c,但是很奇怪，我用code-block不设置highlight也可以）
-
有效的语言:
- none (没有高亮显示)
- python (默认， :confval:`highlight_language` 没有设置时)
- guess (让 Pygments 根据内容去决定, 仅支持一些可识别的语言)
- rest
- c
- ... 其他Pygments 支持的语言名.
-
如果选定语言的高亮显示失败，则模块不会以其他方式高亮显示.
行号
如果安装好, Pygments可以为代码块产生行号.自动高亮显示模块 (以 :: 开始), 行号由指令 highlight 的选项 linenothreshold 管理:
.. highlight:: python
:linenothreshold: 5
如果代码块多于5行将产生行号.
对于 code-block 模块, 选项 linenos 给出则为独立块生成行号:
.. code-block:: ruby
:linenos:
Some more Ruby code.
另外, 选项 emphasize-lines 可以生成特别强调的行:
.. code-block:: 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.'
Changed in version 1.1: 添加了``emphasize-lines`` .
参考：http://zh-sphinx-doc.readthedocs.org/en/latest/markup/code.html
sphinx支持的语言非常之多，参考：http://pygments.org/docs/lexers/
scheme支持：
class pygments.lexers.functional.RacketLexer
| Short names: | racket, rkt |
|---|---|
| Filenames: | *.rkt, *.rktl |
| MIME types: | text/x-racket, application/x-racket |
Lexer for Racket source code (formerly known as PLT Scheme).
New in Pygments 1.6.
如何在.rst中插入代码？
.. literalinclude:: ./code/1.2.3.rkt
:language: rkt
:linenos:
包含：
.. literalinclude:: filename
目录里不显示的文件可能被一个外部纯文本文件保存为例子文本. 文件使用指令 literalinclude 包含. [1] 例如包含Python源文件 example.py, 使用:
.. literalinclude:: example.py
文件名为当前文件的相对路径. 如果是绝对路径 (以 / 开始), 则是源目录的相对路径.
输入标签可以扩展，给出 tab-width 选项指定标签宽度.
该指令也支持 linenos 选项产生行号, emphasize-lines 选项生成强调行, 以及 language 选项选择不同于当前文件使用的标准语言的语言. 例如:
.. literalinclude:: example.rb
:language: ruby
:emphasize-lines: 12,15-18
:linenos:
被包含文件的编码会被认定为 :confval:`source_encoding`. 如果文件有不同的编码，可以使用 encoding 选项:
.. literalinclude:: example.py
:encoding: latin-1
指令支持包含文件的一部分. 例如 Python模块, 可以选择类，函数或方法，使用 pyobject 选项:
.. literalinclude:: example.py
:pyobject: Timer.start
这会包含文件中 Timer 类的 start() 方法后面的代码行.
使用 lines 选项精确的控制所包含的行:
.. literalinclude:: example.py
:lines: 1,3,5-10,20-
包含1, 3, 5 到 10 及 20 之后的代码行.
另一种实现包含文件特定部分的方式是使用 start-after 或 end-before 选项 (仅使用一种). 选项 start-after 给出一个字符串, 第一行包含该字符串后面的所有行均被包含. 选项 end-before 也是给出一个字符串，包含该字符串的第一行前面的文本将会被包含.
可以往包含代码的首尾添加新行，使用 prepend 及 append 选项. 这很有用，比如在高亮显示的PHP 代码里不能包含 <?php/?> 标签.
New in version 0.4.3: 选项 encoding .
New in version 0.6: 选项 pyobject, lines, start-after 及 end-before , 并支持绝对文件名.
New in version 1.0: 选项 prepend 、 append 及 tab-width.
还有一种方式：
插入simple code:
Literal code blocks are introduced by ending a paragraph with the special marker (double coulumn) ::. The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines).
The two following codes:
This is a simple example::
import math
print 'import done'
and:
This is a simple example:
::
import math
print 'import done'
gives:
This is a very simple example:
import math
print 'import done'
By default the syntax of the language is Python, but you can specify the language using thecode-block directive as follows:
.. code-block:: html
:linenos:
<h1>code block example</h1>
参考：http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html
http://openmdao.org/docs/documenting/sphinx.html
http://sphinx-doc.org/markup/code.html
http://zh-sphinx-doc.readthedocs.org/en/latest/markup/code.html