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