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 文件。