3. reStructuredText 介紹

reStructuredText是輕量型標記語言,附檔名為rst的純文字檔,經由Sphinx軟體工具巷可轉換成HTML或pdf等等多稱格式.
我們寫rst文字檔案, 依照reStructuredText的規範,再使用Sphinx的make html指令就可以讓rst文字轉成html.

3.1. 定義文件結構

我們在上個章節 建立文檔html 是依照預設的index.rst所建立html,index主要建立首頁的一個文件樹的結構:

1
2
3
.. toctree::
   :maxdepth: 2
   :caption: Contents:

參考下圖所示toctree說明:

../_images/rst_tutorial_01.jpg

接下來我們建立一個sample.rst檔案並在在index.rst載入sample如下所示:

1
2
3
4
5
6
7
8
Welcome to sphinx sample's documentation!
=========================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   rst/sample

現在可以專注寫sample.rst檔案,因為sphinx已經幫我們作好相關的鏈結.

3.2. 區段章節設定

設定章節很簡單使用路 = - ` : . 『 」 ~ ^ _ * + # 這些字完為底,要注意字元符號需比章節的字要多. 節章的順序是先使用的字元便是頭一節,章節的標頭可以上下都有字完來表示例如:

=================
這是章節的標頭
=================

這是小節
=================

子小節
-----------------

子子小節
~~~~~~~~~~~~~~~~~

3.3. 內文標記(Inline markup)

這是 斜體 , 這是 強調字 ,這是 源碼示例:

這是 *斜體* , 這是 **強調字** ,這是 ``源碼示例``

3.4. 清單和引用 區塊(list and Quote-like)

3.4.1. 清單

  • 這是清單1.
  • 這是清單2.
  1. 數字清單1.
  2. 數字清單2.
  3. 數字清單3.
  4. 數字清單4.
  1. 數字清單1.
  2. 數字清單2.
  3. 數字清單3.

源碼為:

* 這是清單1.
* 這是清單2.

#. 數字清單1.
#. 數字清單2.

#. 數字清單3.
#. 數字清單4.

1. 數字清單1.

#. 數字清單2.
#. 數字清單3.

3.4.2. 引用 (Quote)

項目（最多一行文字）

項目的定義，必須縮排

並且可以包含多個段落

下一個項目
描述.

源碼:

項目（最多一行文字）
  項目的定義，必須縮排

  並且可以包含多個段落

下一個項目
  描述.

3.4.3. 行區塊

這是第一段
這是第二段
這是第三段

源碼:

| 這是第一段
| 這是第二段
| 這是第三段

3.5. 文字區塊(Literal blocks)

這是正常的文字段落. 下面文字段落為源碼示例:

在這區塊內的源碼示例是一個文字區塊
接著是有段行的哦!文字區塊.

這是區塊內的另一個段落.

再一次顯示正常的文字段落.

源碼:

這是正常的文字段落. 下面文字段落為源碼示例::

  在這區塊內的源碼示例是一個文字區塊
  接著是有段行的哦!文字區塊.

  這是區塊內的另一個段落.

再一次顯示正常的文字段落.

3.6. python文件測試區塊(Doctest blocks)

如果你想呈現python即時執行的指令及結果,只要將其複製貼上即可.如下所示:

>>> import  datetime
>>> datetime . datetime . now () . strftime ( "%Y-%m- %d %H:%M:%S" )
'2018-12- 04 09:37:12'

3.7. 表格(Tables)

3.7.1. 方式一

Header row, column 1 (header rows optional) Header 2 Header 3 Header 4
body row 1, column 1 column 2 column 3 column 4
body row 2 Cells may span columns.
body row 3 Cells may span rows.
  • Table cells
  • contain
  • body elements.
body row 4

源碼:

+------------------------+------------+----------+----------+
| 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             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

3.7.2. 方式二

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

源碼:

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
Inputs Output
A B A or B
False False False
True False True
False True True
True True True

源碼:

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

3.8. 欄位清單(Field Lists)

欄位清單是呈現屬性與值的表現,如下:

name:周裕翔
age:18
height:180公分

源碼:

:name: 周裕翔
:age: 18
:height: 180公分

3.9. 角色(Roles)

一個角色或自定義文字角色是內文顯示標記,語法為 :rolename:`content`

3.9.1. 標準的rst角色

  • emphasis:
  • literal:
  • code:
  • math:
  • pep-reference:
  • rfc-reference:
  • strong:
  • subscript:
  • superscript:
  • title-reference:
     

這是重點(:emphasis:)效果-重點

這是文字(:literal:)效果-文字

這是強調(:strong:)效果-強調

這是數學(:math:)效果-\(A_\text{c} = (\pi/4) d^2\)

這是下標(:subscript:)效果-H2O

這是上標(:superscript:)效果-E = mc2

源碼:

這是重點(:literal:`:emphasis:`)效果-:emphasis:`重點`

這是文字(:literal:`:literal:`)效果-:literal:`文字`

這是強調(:literal:`:strong:`)效果-:strong:`強調`

這是數學(:literal:`:math:`)效果-:math:`A_\text{c} = (\pi/4) d^2`

這是下標(:literal:`:subscript:`)效果-H\ :sub:`2`\ O

這是上標(:literal:`:superscript:`)效果-E = mc\ :sup:`2`

請參考(reStructuredText Interpreted Text Roles) http://docutils.sourceforge.net/docs/ref/rst/roles.html

3.9.2. Sphinx 增加的角色

除了標準的角色外,sphinx也定義了不少,如果想要深入了解請參照 sphinx-roles .

3.9.2.1. any

any這個便利的角色試圖盡力為其參考文本找到有效的目標。例如上一章內的 原始與建置目錄是否分離 小節.

原始與建置目錄是否分離

源碼:

:any:`原始與建置目錄是否分離`

3.9.2.2. ref

使用ref角色,一樣是可以找到章節目標,也可以自訂義label標籤讓ref找到.在定義之前請在conf設定 sphinx.ext.autosectionlabel

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autosectionlabel',
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The master toctree document.

原始與建置目錄是否分離

原始與建置目錄是否分離

在getting_started.rst內定義標纖 我的參考標籤

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
.. _我的參考標籤:

原始與建置目錄是否分離
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bat
  :linenos:
 
  Welcome to the Sphinx 1.8.2 quickstart utility.

  Please enter values for the following settings (just press Enter to

源碼:

:ref:`我的參考標籤`

:ref:`原始與建置目錄是否分離`

3.9.2.3. doc

聯結指定文檔,可用相對路徑及絕對路徑 根路徑為/

絕對路徑：

文件編寫工具-sphinx

安裝 sphinx

相對路徑：

文件編寫工具-sphinx

安裝 sphinx

源碼:

 絕對路徑：

:doc:`/index`

:doc:`/rst/installing_sphinx`

相對路徑：

:doc:`../index`

:doc:`installing_sphinx`

3.9.2.4. download

範例 下載index.rst.

源碼:

範例 :download:`下載index.rst <../index.rst>`.

3.9.2.5. numref

可結合文字產生數字編號,例如 圖-1.1,圖-1.2,可聯結有 figures, tables, code-blocks and sections; 請注意,如果numfig為false,請至conf.py內設定為true.如下所示:

1
2
3
4
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']

numfig = True

請參考 下載python

源碼:

1
2
3
4
5
6
7
8
下載python
^^^^^^^^^^^^^^^^
.. figure:: ../img/installing_sphinx_01.jpg
   :scale: 40 %
   :alt: 下載python3
   :name: my_figure
   
:numref:`(圖-%s) <my_figure>`

3.9.2.6. math

數學表示符號

\(a^2 + b^2 = c^2\)

源碼:

:math:`a^2 + b^2 = c^2`

3.9.2.7. abbr

網頁 tool-tip(提示工具),當滑鼠游標移到字元處就會出現提示工具

LIFO-後進先出

源碼:

:abbr:`LIFO-後進先出 (last-in-後進, first-out-先出)`

3.9.2.8. command

呈現作業系統層命令,例如rm.

The name of an OS-level command, such as rm.

源碼:

The name of an OS-level command, such as :command:`rm`.

3.9.2.9. file

呈現檔案或目錄,可以使用大括號來表示 變數 的部份

is installed in C:\Users\tiger\AppData\Local\Programs\Python\Python37-x\Lib\site-packages

is installed in /usr/lib/python2.x/site-packages

3.9.2.10. guilabel

使用guilabel標籤作為交互式使用者界面的一部分呈現, 包含按鈕標籤 button labels ,視窗抬頭 window titles 欄位名稱, field names ,選項單和選單內容名稱 menu and menu selection names ,選項清單的事件值 和 even values in selection lists .

Cancel

源碼:

:guilabel:`&Cancel`

3.9.2.11. kbd

呈現平台或應用程式常用的組合鍵或快速鍵例如下面所示:

C-x C-f

Control-x Control-f.

源碼:

:kbd:`C-x C-f`

:kbd:`Control-x Control-f`.

3.9.2.12. mailheader

RFC 822-style mail header裡的名稱使用mailheader來呈現

Content-Type

源碼:

:mailheader:`Content-Type`

3.9.2.14. mimetype

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

源碼:

:mimetype:`<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />`

3.9.2.15. program

cmd.exe

源碼:

:program:`cmd.exe`

3.9.2.16. regexp

呈現正規表示式的語法

[^0-9]

源碼:

:regexp:`[^0-9]`

3.9.2.17. samp

這是一個文字 literal ,內含 emphasis, 其中使用大刮號內的variable,就是用 emphasis 呈現

print 1+variable

emphasis 字樣- variable

源碼:

:samp:`print 1+{variable}`

emphasis 字樣- :emphasis:`variable`

3.9.2.18. pep

呈現Python增強建議書網址 Python Enhancement Proposal

PEP 333#Phillip J. Eby

源碼:

:pep:`333#Phillip J. Eby`

3.9.2.19. rfc

呈現請求意見稿網址 Request For Comments

RFC 2555#RFC Editor, et al.

RFC 791#IP.

源碼:

:rfc:`2555#RFC Editor, et al.`

:rfc:`791#IP.`

3.9.2.20. 使用角色心得(roles)

在撰寫文件中,使用常用的角色來呈現文章的效果非常方便,但是如果角色太多要記住這麼多指令也是令人傷腦筋, 角色的定義本來就是依照各種文件的不同所產生,所以很多角色的定義確是相同的效果,使用角色可以讓作者更清晰內文的形態, 至於是否強制使用不同的角色就看各人,但有一些角色的定義確實讓人方便,而且寫文件的統一性也會變好.

3.10. 指令(Directives)

指令在rst文件使用上非常普遍,它是reST的擴展機制之一，而且Sphinx大量使用它。

3.10.1. Docutils 提供下列指令

3.10.1.1. 警告(Admonition)

  • attention
  • caution
  • danger
  • error
  • hint
  • important
  • note
  • tip
  • warning

注意

attention 注意!

警示

這是caution.警示！

危險

這是danger.危險！

錯誤

這是error.錯誤！

提示

這是hint.提示！

重要

這是important.重要！

備註

這是note的備註. 這是第二行,但它接續的第一段 .

  • The note 包含所有縮排元素.
  • 它包括list元素.

小訣竅

這是tip.小訣竅！

警告

這是warning.警告！

源碼:

.. attention::
   attention 注意!

.. caution::
   這是caution.警示！

.. danger::
   這是danger.危險！

.. error::
   這是error.錯誤！

.. hint::
   這是hint.提示！

.. important::
   這是important.重要！

.. note::
   這是note的備註.
   這是第二行,但它接續的第一段 .

   - The note  包含所有縮排元素.
   - 它包括list元素.

.. tip::
   這是tip.小訣竅！

.. warning::
   這是warning.警告！

3.10.1.2. 圖片(Images)

圖片的指令有 image 和 figure ,figure 下方縮排文字可以作為圖片的說明, 再上我們在conf.py內設定 numfig = True 所以自動產生圖片編號 literal:Fig. 3.1 如下所示:

python下載頁面







下載檔案

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

原碼:

.. image:: ../img/installing_sphinx_01.jpg
   :height: 200px
   :width: 200 px
   :scale: 80 %
   :alt: python下載頁面
   :align: left

|
|
|
|
|
|
|

.. figure:: ../img/installing_sphinx_02.jpg
   :height: 200px
   :width: 200 px
   :figwidth: 300px
   :scale: 80 %
   :alt: 下載檔案
   :align: center

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

3.10.1.3. 額外的本文內容元素(Additional body elements)

contents 指令

源碼:

.. contents:: 目錄
   :depth: 2
container 指令
container指令會在html內產生一個區塊層(div),可以自訂一個class,從範例class name為custom,
因為是自定義css所以在conf要載入css如下所示:
1
2
def setup(app):
    app.add_stylesheet('custom.css')

在你的 _static 目錄內加入 custom.css ,並填上class的屬性

1
2
3
4
5
div.custom {
	font-size: 16px;
	color:red;
	border-style: dotted;
}

重新make html,你就可以看到如下的結果:

container指令使用使用自訂css來呈現.

源碼:

.. container:: custom

   container指令使用使用自訂css來呈現.

rubric 指令

這是一個標頭的指令,但不會呈現在文件區段的章節

Variables

Variables should be in the camelCase format in all cases.:

var = 3
anotherVar = 4
moreWordsThanPreviousVar = 5

源碼:

.. rubric:: Variables

Variables should be in the ``camelCase`` format in all cases.::

    var = 3
    anotherVar = 4
    moreWordsThanPreviousVar = 5

Topic

產生主題抬頭的區塊

抬頭表題

這是一個在抬頭上面自訂主題的區塊哦,歡迎您的使用.

源碼:

.. topic:: 抬頭表題

    這是一個在抬頭上面自訂主題的區塊哦,歡迎您的使用.

sidebar

側邊區塊的抬頭主題

子抬頭,這是選項

側邊抬頭是在側邊通常用於項目列表.

源碼:

.. sidebar:: 側邊區塊的抬頭主題
   :subtitle: 子抬頭,這是選項

   側邊抬頭是在側邊通常用於項目列表.

parsed-literal

解析區塊內的文字或超鏈結,用普通文字呈現.

( (title, subtitle?)?,
  decoration?,
  (docinfo, transition?)?,
  %structure.model; )

parsed-literal is a literal-looking block with parsed text

源碼:

.. parsed-literal::

   ( (title_, subtitle_?)?,
     decoration_?,
     (docinfo_, transition_?)?,
     `%structure.model;`_ )

.. _title: ../index.html
.. _subtitle: rst_tutorial.html#xxxxxxx
.. _decoration: installing_sphinx.html
.. _docinfo: rst_tutorial.html
.. _transition: getting_started.html
.. _%structure.model;: rst_tutorial.html

.. parsed-literal::

   parsed-literal is a literal-looking block with **parsed** *text*

epigraph

短文,題詞引用或詩

善良，這是一個最單純的辭彙，又是一個最複雜的辭彙。它淺顯到人人都能領會，又深奧到無人能夠定義。它與人終生相伴，但人們卻很少琢磨它、追問它。

—余秋雨

源碼:

.. epigraph::

   善良，這是一個最單純的辭彙，又是一個最複雜的辭彙。它淺顯到人人都能領會，又深奧到無人能夠定義。它與人終生相伴，但人們卻很少琢磨它、追問它。

   -- 余秋雨

highlights

永遠到底有多遠？我們都不知道。所以要做自己想做的事情。要有勇氣去做

compound

The 『rm』 command is very dangerous. If you are logged in as root and enter

cd /
rm -rf *

you will erase the entire contents of your file system.

源碼:

.. compound::

   The 'rm' command is very dangerous.  If you are logged
   in as root and enter ::

       cd /
       rm -rf *

   you will erase the entire contents of your file system.

table

表 3.1 真假值表
A not A
False True
True False

源碼:

.. table:: 真假值表
   :widths: auto

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

CSV Table

表 3.2 旅遊休閒包款!
品名 價格 描述
三折盥洗袋 680 收納一目了然,透氣網層收納袋,多層收納 可隨意掛放
旗艦款電腦旅行後背包 2880 大容量不怕裝,多規格分類收納網袋,3-4天小旅行說走就走
輕便旅行後背包 1980 2~3天小旅行說走就走,上下網層收納袋，收納方便

源碼:

.. csv-table:: 旅遊休閒包款!
   :header: "品名", "價格", "描述"
   :widths: 15, 10, 30

   "三折盥洗袋", 680, "收納一目了然,透氣網層收納袋,多層收納 可隨意掛放"
   "旗艦款電腦旅行後背包", 2880, "大容量不怕裝,多規格分類收納網袋,3-4天小旅行說走就走"
   "輕便旅行後背包", 1980, "2~3天小旅行說走就走,上下網層收納袋，收納方便"

List Table

表 3.3 旅遊休閒包款!
品名 價格 描述
三折盥洗袋 680 收納一目了然,透氣網層收納袋,多層收納 可隨意掛放
旗艦款電腦旅行後背包 2880 大容量不怕裝,多規格分類收納網袋,3-4天小旅行說走就走
輕便旅行後背包 1980 2~3天小旅行說走就走,上下網層收納袋，收納方便

源碼:

.. list-table:: 旅遊休閒包款!
   :widths: 15 10 30
   :header-rows: 1

   * - 品名
     - 價格
     - 描述
   * - 三折盥洗袋
     - 680
     - 收納一目了然,透氣網層收納袋,多層收納 可隨意掛放
   * - 旗艦款電腦旅行後背包
     - 2880
     - 大容量不怕裝,多規格分類收納網袋,3-4天小旅行說走就走
   * - 輕便旅行後背包
     - 1980
     - 2~3天小旅行說走就走,上下網層收納袋，收納方便

raw

使用原始資料

使用原始html標記

源碼:

.. raw:: html

   <hr width=50 size=10>

   <h2>使用原始html標記</h2>

include

Pegasus 設計給愛旅行及愛生活的人們，提供旅行者簡潔

輕巧又實用的隨身好物，想像一下，漫遊在充滿古味的老街之旅，

或者 2~3 天的旅行、 5 天、一周甚至更久，出了家門，隨時都是在體驗旅行生活。

期許人們能在旅程中平安順利，並享受到簡單的美好。

源碼:

.. include:: A.txt

class

class special

This is a 「special」 paragraph.

源碼:

.. class:: special

This is a "special" paragraph.

meta

源碼:

.. meta::
   :description: The reStructuredText plaintext markup language

在html的原始檔中:

<meta content="The reStructuredText plaintext markup language" name="description" />

title

複蓋之前html抬頭

源碼:

.. title:: 自訂義抬頭

3.11. 注腳(Footnotes)

注腳,使用[#nmae]定義,以及使用[#nmae]_方式,會自動產生編號.

使用名稱f1的注腳 [1] 使用名稱f2的注腳 … [2]

注腳使用名稱

[1]第一個注腳的文字解釋.
[2]第二個注腳的文字解釋.

源碼:

使用名稱f1的注腳 [#f1]_ 使用名稱f2的注腳 ... [#f2]_

.. rubric:: 注腳使用名稱

.. [#f1] 第一個注腳的文字解釋.
.. [#f2] 第二個注腳的文字解釋.

3.12. 引用文(Citations)

使用引用文是跟注腳類似,但是他是直接使用名稱,不是自動編號,sphinx額名增加在全域的rst文件中都可以參照.

這是引用文Ref名稱,請滑鼠點 [Ref] .

[Ref]太好了,這個引用文方式的注釋.

源碼:

這是引用文Ref名稱,請滑鼠點 [Ref]_ .

.. [Ref] 太好了,這個引用文方式的注釋.

3.13. 取代(Substitutions)

這個一個警告圖 H 3, 所以國道出現了 H ,要真的注意,假如你忽略 H , 你將會後悔 ,接下來使用 這個取代了 強調 語法的文字 2.

源碼:

這個一個警告圖 |H| 3, 所以國道出現了 |H| ,要真的注意,假如你忽略 |H| ,
你將會後悔 ,接下來使用 |S| 2.

.. |H| image:: ../img/001.png
   :height: 16
   :width: 16

.. |S| replace:: 這個取代了 **強調** 語法的文字

3.14. 備註(Comments)

源碼:

.. 這是一個備註,所以不會呈現在html,在rst內使用.