Sphinx 文件指引

參考文件中的其他章節

若要參考文件中的其他章節，必須先在目標章節上方建立錨點

.. _docs.example.reference:

Example Section Header
----------------------

NOTES:

#.  The reference anchor must start with an underscore, i.e. ``_``.

#.  !! There must be an empty line between the anchor and its target !!

之後即可在文件中的其他地方參考此錨點

Referencing the section :ref:`docs.example.reference` from
another page in the docs.

Referencing the section with
:ref:`custom text <docs.example.reference>` from another page
in the docs.

Note that the prefix underscore is not needed when referencing the anchor.

參考原始碼

可以使用 literalinclude 指令，在 Sphinx 文件中顯示原始碼。若要顯示完整檔案內容

.. literalinclude::  relative/path/from/this/rst/file/to/the/source.txt

若要僅顯示檔案的某個章節，必須先在目標原始碼檔案中加入一對獨特的標籤，以註解的形式，並將標籤字串放在方括號中。

針對 Python 原始碼檔案

# [example.tag.start]

# ... code section that will be referenced ...

# [example.tag.end]

針對 C++ 原始碼檔案

/// @skipline [example.tag.start]

/// ... code section that will be referenced ...

/// @skipline [example.tag.end]

接著需要將標籤提供給 literalinclude 指令

.. literalinclude::  relative/path/from/this/rst/file/to/the/source.cpp
  :language: cpp
  :start-after: example.tag.start
  :end-before: example.tag.end

請參閱 Sphinx 文件 此處 以取得更多資訊。

加入 LaTeX

可以使用 math 指令，將 LaTeX 數學式內嵌加入 Sphinx 文件中

Example text: :math:`k_{n+1} = n^2 + k_n^2 - k_{n-1}`

上述範例將呈現為： \(k_{n+1} = n^2 + k_n^2 - k_{n-1}\)。

數學式也可以程式碼區塊的形式插入

.. math::

  \int_a^bu \frac{d^2v}{dx^2} \,dx
    = \left.u \frac{dv}{dx} \right|_a^b
    - \int_a^b \frac{du}{dx} \frac{dv}{dx} \,dx

\[\int_a^bu \frac{d^2v}{dx^2} \,dx = \left.u \frac{dv}{dx} \right|_a^b - \int_a^b \frac{du}{dx} \frac{dv}{dx} \,dx\]

請參閱 Sphinx 文件 此處 與 此處 以取得更多資訊。

加入圖表

可以使用 graphviz 指令，在 Sphinx 中產生圖表。圖表描述可以加入區塊中

.. graphviz::

  digraph example {
    "From" -> "To";
  }

或者，也可以從外部 .dot 檔案匯入

.. graphviz:: ExampleGraph.dot

請參閱 Sphinx 與 Graphviz 文件以取得更多資訊。