1 附录:reStructuredText简明教程

1.1 段落

标记约定:

一号 ==================== 二号 ——————– 三号 ^^^^^^^^^^^^^^^^^^^^ 四号 “”“”“”“”“”“”“”“”“”“”“

段落块标记;This is a line block. It ends with a blank line.
Each new line begins with a vertical bar (“|”).
Line breaks and initial indents are preserved.
Continuation lines are wrapped portions of long lines; they begin with a space in place of the vertical bar.
The left edge of a continuation line need not be aligned with the left edge of the text above it.
This is a second line block.

Blank lines are permitted internally, but they must begin with a “|”.

1.1.1 Block Quotes

Block quotes consist of indented body elements:

My theory by A. Elk. Brackets Miss, brackets. This theory goes as follows and begins now. All brontosauruses are thin at one end, much much thicker in the middle and then thin again at the far end. That is my theory, it is mine, and belongs to me and I own it, and what it is too.

—Anne Elk (Miss)


1.1.3 侧边栏

1.1.4 复合段落

This paragraph contains a literal block:

Connecting... OK
Transmitting data... OK
Disconnecting... OK

and thus consists of a simple paragraph, a literal block, and another simple paragraph. Nonetheless it is semantically one paragraph.

This construct is called a compound paragraph and can be produced with the “compound” directive.

1.2 二号标题:使用链接

1.2.1 描点链接

目的地: .. _my-reference-label: 这是个描点链接

需引用自身, 查看 my-reference-label. 还是说这样可以:`my-reference-label`_ eg:查看这个文件本身::ref:`_helloworld`_

1.2.2 外部链接

链接文本 可以插入网页链接

使用链接 和其它的方式 colin的博客.

链接文本是网址,则不需要特别标记,分析器会发现网址和邮件;

1.2.3 内部链接

查看 top命令(top_),或者是查看sar命令(sar_),

标记:

使用

使用这个链接:example

本页面链接:helloword_

1.3 尾注

Lorem ipsum 1 dolor sit amet … 2 .. rubric:: Footnotes

1(1,2)

第一条尾注的文本.

2

第二条尾注的文本.

也可以使用自动标号的尾注:3 熟悉Git4的人几乎都知道并喜欢 .. [#] http://git-scm.com/

1.4 引用:

这里有个引用 1 呵呵, .. [#f1] 参考文献

1.5 添加图片

1.5.1 普通图片添加

图片路径为源文件的相对路径;或者以根目录为开始的

reStructuredText, the markup syntax

A figure directive with center alignment

_images/me115_com.jpg

1.5.2 插图引用

_images/me115_com.jpg

插图 6-1 神奇的木书架

引用处: 插图 6-1 神奇的木书架

1.6 内联标记(单词标记)

斜体:text (两侧各留一个空格) 加粗:text 代码样式:text (反引号) 文本中如果有,使用反斜杠进行转义;

Paragraphs contain text and may contain inline markup: emphasis, strong emphasis, inline literals, standalone hyperlinks (http://www.python.org), external hyperlinks (Python_), internal cross-references (example), external hyperlinks with embedded URIs (Python web site), footnote references (manually numbered [1]_, anonymous auto-numbered 5, labeled auto-numbered 6, or symbolic [*]_), citation references ([CIT2002]), substitution references (|example|), and inline hyperlink targets (see Targets_ below for a reference back to here). Character-level inline markup is also possible (although exceedingly ugly!) in reStructuredText. Problems are indicated by |problematic| text (generated by processing errors; this one is intentional).

The default role for interpreted text is Title Reference. Here are some explicit interpreted text roles: a PEP reference (PEP 287); an RFC reference (RFC 2822); a subscript; a superscript; and explicit roles for standard inline markup.

1.7 列表:

仅在段落的开头放置一个星号和一个缩进. 编号的列表也可以;也可以使用符号 # 自动加序号:

  • 这是一个项目列表

  • 有两项

用-是markdown的做法,rst同样可用:

  • hello,第一列

  • 第二列

  • 第三列

  1. 这是个有序列表

  2. 还是个有序列表,自动编号

注:列表可以嵌套,但是使用空行分割

1.7.1 名称解释列表:

大CC

大CC的博客在这里

1.8 Definition Lists

Term

Definition

Termclassifier

Definition paragraph 1.

Definition paragraph 2.

1.9 Bullet Lists

  • A bullet list

    • Nested bullet list.

    • Nested item 2.

  • Item 2.

    Paragraph 2 of item 2.

    • Nested bullet list.

    • Nested item 2.

      • Third level.

      • Item 2.

    • Nested item 3.

1.10 特殊段落标记

Note

这里是Note提示段落;

其它类似语法的还有:

  • warning 一般显示的是信息安全方面的注意事项

  • seealso 许多章节包含模块文档或者扩展文档的参考索引列表.这些列表由指令 seealso 创建

  • centered 创建居中加粗文本行

  • hlist 生成水平列表. 它将列表项横向显示并减少项目的间距使其较为紧凑

水平列表,它将列表项横向显示并减少项目的间距使其较为紧凑

1.10.1 提示框

Attention

Directives at large.

Caution

Don’t take any wooden nickels.

Danger

Mad scientist at work!

Error

Does not compute.

Hint

It’s bigger than a bread box.

Important

  • Wash behind your ears.

  • Clean up your room.

  • Call your mother.

  • Back up your data.

Note

This is a note.

Tip

15% if the service is good.

Warning

Strong prose may provoke extreme mental exertion. Reader discretion is strongly advised.

And, by the way…

You can make up your own admonition too.

See also

本书并非一本介绍Git的书,并且假设读者已经掌握了Git的相关操作。如果读者对Git尚不了解,可以参考我写的 《Git权威指南》7一书。此外还可以从网上找到很多免费的、很好的Git资料,如:Git社区书[#]_、Pro Git[#]_等。

可以通过多行缩进产生多行评论:

1.11 源代码标记

这个 :: 标记很优雅:(下一行需要跟一个空白行) - 如果作为独立段落存在,则整段都不会出现在文档里. - 如果前面有空白,则标记被移除. - 如果前面是非空白,则标记被一个冒号取代.

for(int i = 0;i< 10 ;i++)
{
    cout << "hello world" << endl;
}

高亮语法的标记:

1
2
3
def foo():
    print "Love Python, Love FreeDome"
    print "E文标点,.0123456789,中文标点,. "
/opt/app/todeav1$ps -fe| grep ls
root      3676     1  0  2012 ?        02:58:14 /usr/sbin/vmtoolsd
3

http://git-scm.com/

4

https://github.com/

5

ISBN:9787111349679, 由机械工业出版社华章公司于2011年7月出版。

6

http://book.git-scm.com/

7

http://progit.org/book/

1.12 替换文本

I recommend you try |Python|_.

Topic Title

This is a topic.

This is a rubric

1.13 表格

Author

David Goodger

Address

123 Example Street Example, EX Canada A1B 2C3

Contact

docutils-develop@lists.sourceforge.net

Authors

Me; Myself; I

Dedication

For Docutils users & co-developers.

abstract

This document is a demonstration of the reStructuredText markup language, containing examples of all basic reStructuredText constructs and many advanced constructs.