示例的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: 选项 pyobjectlinesstart-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

sphinx插入代码的更多相关文章

  1. Bootstrap css栅格 + 网页中插入代码+css表格

    设计达人 http://www.shejidaren.com/30-minimal-app-icons.html CSS栅格: <!DOCTYPE html> <html lang= ...

  2. 使用Markdown在博客里插入代码

    今天尝试了一下在线使用Markdown编辑器写博客,发现想要实现下面这样的效果还真得折腾一会儿. <html> <head> <meta charset="ut ...

  3. 怎样在Word中插入代码并保持代码原始样式不变

    怎样在Word中插入代码并保持样式不变 我们有时候需要在word中添加一段我们写的代码,但是把代码粘贴到word文档中之后就发现所有的代码的样子都变了,我们可以采用下边的方法来实现保持代码原来的样式和 ...

  4. PE头的应用---插入代码到EXE或DLL文件中

    三.代码实现(DELPHI版本),采用第三种方式实现代码插入. 1. 定义两个类,一个用来实现在内存中建立输入表:一个用来实现对PE头的代码插入. DelphiCode: const MAX_SECT ...

  5. 编程算法 - 有序双循环链表的插入 代码(C)

    有序双循环链表的插入 代码(C) 本文地址: http://blog.csdn.net/caroline_wendy 有序双循环链表的插入, 须要找到插入位置, 能够採用, 两个指针, 一个在前, 一 ...

  6. xhEditor实现插入代码功能

    如果大家经常使用CSDN或者其他技术博客,都会有插入程序代码或脚本功能 开源中国 CSDN 这里介绍xhEditor实现插入代码功能,对xhEditor进行插件扩展 一.首先定义插件样式 <st ...

  7. 在word中如何美观地插入代码

    打开这个网站 http://www.planetb.ca/syntax-highlight-word 进去后我们看到下面的界面 中间的空白文本框,可以插入代码,下面可以选择代码种类,最后点击Show ...

  8. 在word中优雅地插入代码

    PlanetB:带行号 http://www.planetb.ca/syntax-highlight-word   Pygments(推荐):不带行号,多种样式可选 http://pygments.o ...

  9. php插入代码数据库

    插入代码:<?php $con = mysql_connect("localhost","peter","abc123"); if ( ...

随机推荐

  1. IO之流程与buffer 图

    http://blog.chinaunix.net/uid-29075379-id-3944364.html

  2. systemtap [主设备号,次设备好,inode]监控文件

    SystemTap 是监控和跟踪运行中的linux 内核的操作的动态方法,SystemTap 应用:对管理员,SystemTap可用于监控系统性能,找出系统瓶颈,而对于开发者,可以查看他们的程序运行时 ...

  3. Hadoop WritableComparable接口

    WritableComparable接口 Writable接口大家可能都知道,它是一个实现了序列化协议的序列化对象.在Hadoop中定义一个结构化对象都要实现Writable接口,使得该结构化对象可以 ...

  4. mysql 存储过程项目小结

    1. false :0  true 1 切记 官方文档:http://dev.mysql.com/doc/refman/5.0/en/numeric-type-overview.html BOOL,  ...

  5. 最近的两个小项目,2:Python webapp的docker镜像

    时间过得真快,一眨眼一个多月没更新了,但这一个月我可没偷懒啊,真的是忙.粘上两篇ReadMe勉强凑合一下,保持博客更新是好习惯. 基于Flask框架,uwsgi起服务,supervisor做管理,应该 ...

  6. noi1816 画家问题(技巧搜索Dfs)

    /* Problem 画家问题 假设一个ans数组存的是对每一个点的操作 0表示不图 1表示图 那么 对于原图 g 操作第三行时对第一行没有影响 同样往下类似的 所以 假设我们知道了ans的第一行就是 ...

  7. Android开发文摘集合1

    作者:张明云 原标题:Android 开发中,有哪些坑需要注意? 作者github主页:zmywly8866.github.io/ 在Android library中不能使用switch-case语句 ...

  8. html招聘简历解析并入库测试

    1.解析4天,一天用来熟悉Jsoup 2.入库,需要熟悉什么样的格式代码可以入库,将自己解析好的代码转为指定格式.总体框架的构建, 如何执行,需要读他人写的代码(很费时间).4天,包括晚上九点加班三天 ...

  9. 【转】 iOS开发之手势gesture详解

    原文:http://www.cnblogs.com/salam/archive/2013/04/30/iOS_gesture.html 前言 在iOS中,你可以使用系统内置的手势识别 (Gesture ...

  10. HTML页面中启用360浏览器极速模式

    今天做页面突然遇到浏览器一直在兼容模式下运行,体验不好,通过查询文档,在<head>中加入<meta name="renderer" content=" ...