注册 登录  
 加关注
   显示下一条  |  关闭
温馨提示!由于新浪微博认证机制调整,您的新浪微博帐号绑定已过期,请重新绑定!立即重新绑定新浪微博》  |  关闭

guoyoooping的博客

audio,picture, text and video

 
 
 

日志

 
 

reStructuredText语法  

2017-05-09 18:39:54|  分类: 默认分类 |  标签: |举报 |字号 订阅

  下载LOFTER 我的照片书  |
rst语法
*******
试试网易博客支不支持rst语法.

:Date: 2017-05-09
:Version: 1
:Authors: - ypguo

1. 标题
=======

标题的格式, 参考本文的文档标题.


1) 可以使用字母数字以外的可打印ACSII字符,官方推荐的是以下字符:

    "``= - ` : ' " ~ ^ _ * + # < >``"

2) 标题前后的符号数目必须大于等于标题文本的长度

更深层的标题如下:

1.1 二级标题
------------

三级标题
~~~~~~~~

四级标题
""""""""

2. 段落
=======

段落是被空行分割,左侧对齐,有相同缩进的一段文本::

    +------------------------------+
    | paragraph                    |
    |                              |
    +------------------------------+

    +------------------------------+
    | paragraph                    |
    |                              |
    +------------------------------+


段落不需要特殊标记,用空行来分割,
段落内的换行是被忽略的,因此源文件
可以很好地控制一行的长度。

如果想保留换行符,需要参考3.2来实现

3. 引用
=======
   
3.1 文字引用
------------

::

    +------------------------------+
    | paragraph                    |
    | (ends with "::")             |
    +------------------------------+
       +---------------------------+
       | indented literal block    |
       +---------------------------+

引用一段文字用"::"标记,"::"可以在段尾,也可以单独占用一个空行。 引用的段落靠
缩进标识,到缩进结束的时候为止,引用段落的所有格式都会被被保留。包括行首的空格
以及结束符等::

    这个 :: 标记很优雅:
        如果作为独立段落存在,则整段都不会出现在文档里.

    如果前面有空白,则标记被移除.
        如果前面是非空白,则标记被一个冒号取代.
            引用直到相缩进结束
    
                引用块的前后要有空行,但空行不会被当成引用的内容。


代码段(参考下文)可以看成更加特殊的引用,不但保留段落格式,还可以显示不同编程语
言的语法高亮。

3.2 引用行模块
--------------

如果只需要保留行尾换行符,可以在需要引用的块前行首加"| ",

| 你
| 一会儿看我
| 一会儿看云
| 我觉得
| 你看我时很远
| 你看云时很近
|

4. 行内标记
===========

用来实现斜体、粗体、引用、脚注、引用等等:

    *斜体*
    **粗体**
    ``inline quoto``
    H\ :sub:`2`\ O
    E = mc\ :sup:`2`

还有更多其他标记,请参考文档[2].

5. 超链接
=========

1) 直接使用网址:

    http://yongchen.org

    mailto:://ttt@abc.com

2) 用文字表示链接, 内部定义:

    这篇文章来自我的Github,请参考 `Seay Xu <https://github.com/SeayXu/>`_。

3) 用文字表示链接, 单独定义:

    段落里包含 `pypi website`_.

.. _pypi website: https://pypi.python.org/pypi

4) 所有的章节标题都可以被引用:

    比如跳转到 `1. 标题`_

5) 自定义的内部锚点:

    点击这里可以中转到 引用文档_

.. _引用文档:

6) 脚标

    footnote reference [11]_

.. [11] A footnote example linked to [11].

7) 文献引用,和脚标用法类似

    citation reference [CIT2002]_

.. [CIT2002] A citation example.

6. 项目编号
===========

列表标记的使用最自然: 仅在段落的开头放置一个星号和一个缩进. 列表项可以拆行,
对齐则自动续行。列表项可包含多个段落。空行开始新的段落, 新段落要和列表项内容
对齐。列表下的代码段注意对齐即可。

6.1 无序列表
------------

    * 注意1: 项目前后要加上空行
    * 注意2: 项目符号后必须跟一个空格
    * 注意3: 星号、减号、加号开始列表
        + 列表层级和缩进有关。
            - 和具体符号无关。
    * 返回一级列表。

6.2 有序列表
------------

    1) 数字和点是一种编号方式。
        A 大写字母编号。
            a 小写字母编号。
    2) 继续一级列表。
        I 大写罗马编号。
            i 小写罗马编号。

7. 表格
=======

支持两种表格. 一种是"网格表格", 可以自定义表格的边框,一种是简单表格,书写简单
, 但有一些限制: 需要有多行,且第一列元素不能分行显示,如下:

6.1 网格表格
------------

    +------------------------+------------+----------+----------+
    | Header row, column 1   | Header 2   | Header 3 | Header 4 |
    | (header rows optional) |            |          |          |
    +========================+============+==========+==========+
    | body row 1, column 1   | column 2   | column 3 | column 4 |
    +------------------------+------------+----------+----------+
    | body row 2             | ...        | ...      |          |
    +------------------------+------------+----------+----------+

6.2 简单表格
------------

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

6.3 csv-table
-------------

csv 表格利用CSV数据(comma-separated values)自动生成表格, 数据可以为数据,或者
从别的文件里引用过来, csv表格格式如下,详情请参考"reStructuredText Directives"
[1]_::

    .. csv-table:: 表格名字
        :class: text
        :name: text, 可用于生成内部链接
        :widths : integer [, integer...] or "auto"
        :header-rows : integer
        :stub-columns : integer
        :header : CSV data
        :file : string (newlines removed)
        :url : string (whitespace removed)
        :encoding : name of text encoding
        :delim : char | "tab" | "space"
        :keepspace : flag
        :escape : char
        :align : "left", "center", or "right"

        csv data

An example:

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 10, 10, 60
   :align: center

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones
   out, it wouldn't be crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

8. 指令
=======

指令是显式标记最常用的模块. 也是reST的扩展规则, 在 Sphinx 经常被用到.

指令有名字,参数,选项及内容组成. 选项在参数后给出,由冒号引出. 选项必须与指令
有一样的缩进. 指令的内容在隔开一个空行后,与指令有一样缩进::

    +-------+-------------------------------+
    | ".. " | directive_type "::" directive |
    +-------+ block                         |
            |                               |
            +-------------------------------+

8.1 image
---------

"image"就是一张图(对比和figure 的区别), 下面是image 的语法描述::

    .. image:: picture.png
        :name: text
        :class: text
        :alt : text
        :height : length
        :width : length or percentage of the current line width
        :scale : integer percentage (the "%" symbol is optional)
        :alt : Alternate text
        :align : "top", "middle", "bottom", "left", "center", or "right"
        :target : text (URI or reference name)

An example:

.. image:: ./images/funny.jpg
   :scale: 100%
   :alt: funny cat picture
   :align: center
   :name: funny.jpg

image 也可用于代替文字出现在正文中:

    The |biohazard| symbol must be used on containers used to dispose of
    medical waste.

.. |biohazard| image:: ./images/funny.jpg
   :height: 20
   :width: 20

8.2 figure
----------

figure比image包含更多的信息,除了包含一个image, 还可以包含标题,图例,对于基于
页的媒体,figure 可以选择位置以方便页面布局, 下图是figure 和 image 的关系::

    +---------------------------+
    |        figure             |
    |                           |
    |<------ figwidth --------->|
    |                           |
    |  +---------------------+  |
    |  |     image           |  |
    |  |                     |  |
    |  |<--- width --------->|  |
    |  +---------------------+  |
    |                           |
    |The figure's caption should|
    |wrap at this width.        |
    +---------------------------+

使用说明::

    .. figure:: picture.png
       :align : "left", "center", or "right"
       :figwidth : "image", length, or percentage of current line width
       :figclass : text

       This is the caption of the figure (a simple paragraph).

       This is the legend of figure: In this case, the legend consists
       of this paragraph and the following table:

       +-----------------------+-----------------------+
       | Symbol                | Meaning               |
       +=======================+=======================+
       | .. image:: tent.png   | Campground            |
       +-----------------------+-----------------------+
       | .. image:: waves.png  | Lake                  |
       +-----------------------+-----------------------+
       | .. image:: peak.png   | Mountain              |
       +-----------------------+-----------------------+

An example:

.. figure:: ./images/funny.jpg
   :alt: A funny cat
   :figclass: center
   :figwidth: 80%
   :align: center

   figure 1. A funny cat

   This is the legend of the funny cat: the legend consists of anything you
   would add.

8.3 code
--------

语法说明, 详情请参考"reStructuredText Directives" [1]_::

    .. code:: language
        :number-lines : [start line number]
        :name: text
        :class: text

        code, 这个支持的不太好,建议大家用code-block.

            Awk, C, C++, C#, D, Delphi, PHP, Perl, PostScript,
            PowerShell, Python, VHDL,VB, ...
        
        Other markup:

            Apache, Bash, CMake, CSS, Debian, Diff, Gnuplot, HTML,
            Makefiles, Wiki, MySQL, Nginx, ReST, MySQL, TeX, tcsh,
            Vim, XML, YAML, ...

sphinex 貌似还有一个code-block 的指令,语法如下::

    .. code-block:: python
        :emphasize-lines: 3,5
        :lineno-start:
        :linenos:
        :caption: this.py
        :name: this-py
        :dedent: 4
        :emphasize-lines: 3,5
        :name: text
        :class: text

        support those languages: C C++ C# Mathemat CSS Json HTML XML
        JavaScript Julia Julia Java LaTeX Matlab Python Bash Console Batch
        MSDOS Session PowerShell

1) python code

.. code-block:: python
    :linenos:

    def say_hello():
        print 'Hello, ReST'

    if __name__ == '__main__':
        say_hello()                                                       

2) C code
                                                                
.. code-block:: c
    :linenos:
    :lineno-start: 5
    :emphasize-lines: 9
    :name: Init the hash table
    
    /*Init the hash table. */
    void initHashTable(table* t)
    {
        int i;
        if (t == NULL)return;

        for (i = 0; i < BUCKETCOUNT; ++i) {
            t->bucket[i].key = NULL;
            t->bucket[i].value = NULL;
            t->bucket[i].next = NULL;
        }
    }

3) vim script
                                                                
.. code:: vim

    " 是否打开语法高亮, 使得Vim可以用不同的字体或颜色显示文本的不同部分
    syntax on
    " Enable filetype "detection", "indenting" and "plugins"
    filetype plugin indent on
    " Always show current positions along the bottom
    set ruler
    set more       " use more prompt
    set number     " line numbers
    set cursorline " Highlight the screen line of the cursor
    set hidden     " change buffer without saving

8.4 contents
------------

目录用 contents 生成, 语法如下::

    .. contents:: 目录
        :depth : integer
        :local : flag (empty)
        :backlinks : "entry" or "top" or "none"
        :class : text

目录通常可以由sphinx 或者wkhtmltopdf 自动生成,所以文档一般不用自己生成
目录.

8.5 sidebar
-----------

Sidebars are like miniature, parallel documents that occur inside other
documents, providing related or reference material::

    .. sidebar:: Sidebar Title
       :subtitle: Optional Sidebar Subtitle

       Subsequent indented lines comprise
       the body of the sidebar, and are
       interpreted as body elements.

For example:

.. sidebar:: 侧边栏标题
   :subtitle: 子标题

    These lines are sidebar content interpreted as body elements.

    Subsequent indented lines comprise
    the body of the sidebar, and are
    interpreted as body elements.

8.6 math
--------

用于向文档里插入数字公式。需要安装额外的模块,暂时还没有搞定::

    Directive Type:    "math"
    Doctree Element:    math_block
    Directive Arguments:    One, optional: prepended to content.
    Directive Options:    :class:, :name:
    Directive Content:    Becomes the body of the math block. (Content blocks
        separated by a blank line are put in adjacent math blocks.)
    Configuration Setting:
            math_output

    .. math::
    
      α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)


8.7 Admonitions
----------------

包含"attention", "caution", "danger", "error", "hint", "important", "note",
 "tip", "warning" 以及一般性的 "admonition"

DANGER:


.. attention:: Attention, please
.. caution:: Be caution!!!

.. danger::
   modify at your own risk!

.. error:: must be error!
.. hint:: You can open it in another time!
.. important:: Shutdown every saterday!
.. note:: will not support in later version!
.. tip:: open it by right click.
.. warning:: might be memory leak!

8.8 hlist
---------

hlist can be use to set a list on several columns. It seems that it's only
accepted by sphinx.

.. hlist::
    :columns: 3

    * first item
    * second item
    * 3d item
    * 4th item
    * 5th item

8.9 file includes
-----------------

有时候可以直接引用本地文件中的一部分,并且把它们解析成期望的语言::

    .. include:: filename
        :start-line : integer
        :end-line : integer
        :start-after : text to find in the external data file
        :end-before : text to find in the external data file
        :literal : flag (empty)
        :code : formal language (optional)
        :number-lines : [start line number]
        :encoding : name of text encoding
        :tab-width : integer

9. 注释
========

注释以..开头,后面接注释内容即可,可以是多行内容,多行时每行开头要加一个空格。

..
 我是注释内容
 你们看不到我

[参考资料]

.. [1] reStructuredText Directives, http://docutils.sourceforge.net/docs/ref/rst/directives.html
.. [2] Showing code examples, http://www.sphinx-doc.org/en/stable/markup/code.html
.. [3] reStructuredText(rst)快速入门语法说明 http://www.cnblogs.com/seayxu/p/5603876.html
.. [4] reStructuredText Notes, http://yongchen.org/posts/reStructuredText-notes/
.. [5] Sphinx and RST syntax guide, https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
.. [6] 使用reStructuredText来生成精美的PDF文件, http://www.zlovezl.cn/articles/restructuredtext-to-pdf/
.. [7] Sphinx Themes and Pygments Styles, https://www.florian-diesch.de/doc/sphinx/themes-and-pygments-styles/
.. [8] sphinx 生成中文 PDF, http://seisman.info/chinese-support-for-sphinx.html
.. [9] Creating a document in LaTeX, https://www.sharelatex.com/learn/Creating_a_document_in_LaTeX
  评论这张
 
阅读(15)| 评论(0)
推荐 转载

历史上的今天

评论

<#--最新日志,群博日志--> <#--推荐日志--> <#--引用记录--> <#--博主推荐--> <#--随机阅读--> <#--首页推荐--> <#--历史上的今天--> <#--被推荐日志--> <#--上一篇,下一篇--> <#-- 热度 --> <#-- 网易新闻广告 --> <#--右边模块结构--> <#--评论模块结构--> <#--引用模块结构--> <#--博主发起的投票-->
 
 
 
 
 
 
 
 
 
 
 
 
 
 

页脚

网易公司版权所有 ©1997-2017