.. _sphinx-fs: http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html

.. meta::
   :http-equiv=Content-Type: text/html; charset=utf-8
   
**********************
reStructuredText 介紹
**********************
reStructuredText是輕量型標記語言,附檔名為rst的純文字檔,經由Sphinx軟體工具巷可轉換成HTML或pdf等等多稱格式.
 我們寫rst文字檔案, 依照reStructuredText的規範,再使用Sphinx的make html指令就可以讓rst文字轉成html.

定義文件結構
======================================

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

.. literalinclude:: ../tmp/index.rst
   :language: rst
   :linenos:
   :lines: 9-11
   
參考下圖所示toctree說明: 
 
.. image:: ../img/rst_tutorial_01.jpg
   :scale: 50 %

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

.. literalinclude:: ../tmp/index.rst
   :language: rst
   :linenos:
   :lines: 6-14

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

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

   =================
   這是章節的標頭
   =================
   
   這是小節
   =================
   
   子小節
   -----------------
   
   子子小節
   ~~~~~~~~~~~~~~~~~

內文標記(Inline markup)   
=============================
這是 *斜體* , 這是 **強調字** ,這是 ``源碼示例``::

  這是 *斜體* , 這是 **強調字** ,這是 ``源碼示例``
  
清單和引用 區塊(list and Quote-like) 
===========================================

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

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

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

1. 數字清單1.

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

源碼為::

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

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

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

  1. 數字清單1.

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

引用 (Quote)  
--------------------------
項目（最多一行文字）
  項目的定義，必須縮排

  並且可以包含多個段落

下一個項目
  描述.
   
源碼::
 
  項目（最多一行文字）
    項目的定義，必須縮排

    並且可以包含多個段落

  下一個項目
    描述.   

行區塊
---------------------- 
| 這是第一段
| 這是第二段
| 這是第三段

源碼::

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

文字區塊(Literal blocks)
==========================
這是正常的文字段落. 下面文字段落為源碼示例::

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

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

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

源碼::

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

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

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

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

python文件測試區塊(Doctest blocks)
==================================
如果你想呈現python即時執行的指令及結果,只要將其複製貼上即可.如下所示:

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

表格(Tables)
================================
方式一
--------------
+------------------------+------------+----------+----------+
| 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.    |
+------------------------+------------+---------------------+

源碼::

  +------------------------+------------+----------+----------+
  | 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.    |
  +------------------------+------------+---------------------+

方式二
-----------------
=====  =====  =======
  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
  =====  =====  ======

欄位清單(Field Lists)
============================
欄位清單是呈現屬性與值的表現,如下:

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

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

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

標準的rst角色
------------------------

.. hlist::
    :columns: 5
    
    * :emphasis:
    * :literal:
    * :code:
    * :math:
    * :pep-reference:
    * :rfc-reference:
    * :strong:
    * :subscript:
    * :superscript:
    * :title-reference:

這是重點(: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`

源碼::
  
  這是重點(: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

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

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

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

源碼::

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

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

.. literalinclude:: ../conf.py
   :language: python
   :linenos:
   :lines: 37-53

:ref:`我的參考標籤`

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

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

.. literalinclude:: getting_started.rst
   :language: rst
   :linenos:
   :lines: 35-46

源碼::
  
  :ref:`我的參考標籤`

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

doc  
~~~~~~~~~~~~  
聯結指定文檔,可用相對路徑及絕對路徑  :literal:`根路徑為/` 

絕對路徑：

:doc:`/index`

:doc:`/rst/installing_sphinx`

相對路徑：

:doc:`../index`

:doc:`installing_sphinx`

源碼::
  
   絕對路徑：

  :doc:`/index`

  :doc:`/rst/installing_sphinx`

  相對路徑：

  :doc:`../index`

  :doc:`installing_sphinx`
  
download
~~~~~~~~~~~~~~~~

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

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

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

.. literalinclude:: ..\conf.py
   :language: python
   :linenos:
   :lines: 180-183


請參考 :any:`下載python`

源碼:

.. literalinclude:: installing_sphinx.rst
   :language: rst
   :linenos:
   :lines: 18-27

math
~~~~~~~~~~~~~~~
數學表示符號

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

源碼::

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

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

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

源碼::

  :abbr:`LIFO-後進先出 (last-in-後進, first-out-先出)`
  
  
command
~~~~~~~~~~~~~~
呈現作業系統層命令,例如rm.

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


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

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

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

is installed in :file:`/usr/lib/python2.{x}/site-packages`

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

:guilabel:`&Cancel`

源碼::
  
  :guilabel:`&Cancel`
  
kbd
~~~~~~~~~~~~~~~
呈現平台或應用程式常用的組合鍵或快速鍵例如下面所示:

:kbd:`C-x C-f`

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

源碼::

  :kbd:`C-x C-f`

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

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

:mailheader:`Content-Type`

源碼::

  :mailheader:`Content-Type`
  
menuselection
~~~~~~~~~~~~~~

:menuselection:`Start --> &Programs`

源碼::

  :menuselection:`Start --> &Programs`

mimetype
~~~~~~~~~~~~~~~~

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

源碼::

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

program
~~~~~~~~~~~~~~~

:program:`cmd.exe`

源碼::

  :program:`cmd.exe`
  
regexp
~~~~~~~~~~~~~~~
呈現正規表示式的語法

:regexp:`[^0-9]`

源碼::

  :regexp:`[^0-9]`
  
samp
~~~~~~~~~~~~~~~
這是一個文字 :literal:`literal` ,內含 :literal:`emphasis`,
其中使用大刮號內的variable,就是用 :literal:`emphasis` 呈現

:samp:`print 1+{variable}`

emphasis 字樣- :emphasis:`variable`



源碼::

  :samp:`print 1+{variable}`

  emphasis 字樣- :emphasis:`variable`
  
  
  

pep
~~~~~~~~~~~~~~~
呈現Python增強建議書網址 :literal:`Python Enhancement Proposal`

:pep:`333#Phillip J. Eby`

源碼::

  :pep:`333#Phillip J. Eby`
  
rfc
~~~~~~~~~~~~~~~
呈現請求意見稿網址 :literal:`Request For Comments`

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

:rfc:`791#IP.`

源碼::

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

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

Docutils 提供下列指令
------------------------

警告(Admonition)
~~~~~~~~~~~~~~~~~~~~~~~~

.. hlist::
    :columns: 5
    
    * attention
    * caution
    * danger
    * error
    * hint
    * important
    * note
    * tip
    * warning
    
.. attention::
   attention 注意!
 
.. caution::
   這是caution.警示！ 
  
.. danger::
   這是danger.危險！
  
.. error::
   這是error.錯誤！
   
.. hint::
   這是hint.提示！
   
.. important::
   這是important.重要！

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

   - The note  包含所有縮排元素.
   - 它包括list元素.
      
.. tip::
   這是tip.小訣竅！
   
.. warning::
   這是warning.警告！
   
源碼::

  .. attention::
     attention 注意!
 
  .. caution::
     這是caution.警示！ 
  
  .. danger::
     這是danger.危險！
  
  .. error::
     這是error.錯誤！
   
  .. hint::
     這是hint.提示！
   
  .. important::
     這是important.重要！

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

     - The note  包含所有縮排元素.
     - 它包括list元素.
      
  .. tip::
     這是tip.小訣竅！
   
  .. warning::
     這是warning.警告！ 

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

.. 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).

原碼::
  
  .. 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).

額外的本文內容元素(Additional body elements)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:literal:`contents 指令`

.. contents:: 目錄
   :depth: 2
   
源碼::

  .. contents:: 目錄
     :depth: 2

:literal:`container 指令`
 | container指令會在html內產生一個區塊層(div),可以自訂一個class,從範例class name為custom,
 | 因為是自定義css所以在conf要載入css如下所示:

.. literalinclude:: ..\conf.py
   :language: python
   :linenos:
   :lines: 185-186

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

.. literalinclude:: ..\_static\custom.css
   :language: css
   :linenos:
   :lines: 1-6

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

.. container:: custom

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

源碼::

  .. container:: custom

     container指令使用使用自訂css來呈現.
     
     
:literal:`rubric 指令`
     
這是一個標頭的指令,但不會呈現在文件區段的章節

.. 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
  
.. rubric:: Topic

產生主題抬頭的區塊
    
.. topic:: 抬頭表題

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

  .. topic:: 抬頭表題

      這是一個在抬頭上面自訂主題的區塊哦,歡迎您的使用.
 
.. rubric:: sidebar 
    
.. sidebar:: 側邊區塊的抬頭主題
   :subtitle: 子抬頭,這是選項
   
   側邊抬頭是在側邊通常用於項目列表.

源碼::
    
  .. sidebar:: 側邊區塊的抬頭主題
     :subtitle: 子抬頭,這是選項
  
     側邊抬頭是在側邊通常用於項目列表.
  

.. rubric:: parsed-literal
   
解析區塊內的文字或超鏈結,用普通文字呈現.   
   
.. 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*  
  
源碼::    

  .. 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*  


.. rubric:: epigraph

短文,題詞引用或詩

.. epigraph::

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

   -- 余秋雨
   
源碼::

  .. epigraph::

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

     -- 余秋雨

.. rubric:: highlights

.. highlights::
   
   永遠到底有多遠？我們都不知道。所以要做自己想做的事情。要有勇氣去做
   
.. rubric:: compound
   
.. 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. 

.. rubric:: table

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

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

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

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

.. rubric:: CSV Table

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

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

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

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

.. rubric:: List Table

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

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

源碼::

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

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

.. rubric:: raw
  
使用原始資料

.. raw:: html

   <hr width=50 size=10>
   
   <h2>使用原始html標記</h2>
   
源碼::

  .. raw:: html

     <hr width=50 size=10>
   
     <h2>使用原始html標記</h2>  

.. rubric:: include
 
.. include:: A.txt
   
源碼::

  .. include:: A.txt

.. rubric:: class
   
.. class:: special

This is a "special" paragraph.

源碼::

  .. class:: special

  This is a "special" paragraph.
 
.. rubric:: meta
  
.. meta::
   :description: The reStructuredText plaintext markup language
   
源碼::

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

在html的原始檔中::

  <meta content="The reStructuredText plaintext markup language" name="description" />
  
.. rubric:: title
  
複蓋之前html抬頭
  
.. title:: 自訂義抬頭

源碼::

  .. title:: 自訂義抬頭
  

.. default-role:: subscript


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

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

.. rubric:: 注腳使用名稱

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

源碼::

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

  .. rubric:: 注腳使用名稱

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


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

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

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

源碼::

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

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


取代(Substitutions)
==============================

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

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

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

源碼::

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

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

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


備註(Comments)
==============================

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

源碼::

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


.. _sphinx-roles:   http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html