使用QuTiP文档

用户指南提供了QuTiP功能的概述。该指南由单独的重构文本（.rst）文件组成，每个文件都被渲染为一个网页。每个页面通常处理一个功能领域。要了解更多关于如何编写.rst文件的信息，遵循sphinx指南是有用的。

文档构建还利用了多个 Sphinx 扩展包括但不限于 doctest, autodoc, sphinx gallery 和 plot。可以在 conf.py 文件中配置其他扩展。

指令

用户指南中有两个Sphinx指令可用于编写代码示例：

Doctest
Plot

有关每个指令使用的更全面说明，请参阅各自的页面。这里我们概述了一些在制作用户指南时如何使用这些指令的一般准则。

Doctest

doctest 指令允许对交互式代码示例进行测试。最简单的方法是指定一个提示符及其相应的输出：

.. doctest::

    >>> a = 2
    >>> a
    2

这在文档中呈现如下：

>>> a = 2
>>> a
2

在.. doctest::指令下指定代码示例时，所有语句必须由>>>提示符指定或不使用它。对于每个提示符，任何潜在的相应输出必须立即在其后指定。当需要快速连续检查多个示例时，理想情况下使用此指令。

指定代码示例（并测试它们）的另一种方法是使用相关的.. testcode::指令，这实际上是一个代码块：

.. testcode::

    a = 2
    print(a)

接下来是它的结果。结果可以使用 .. testoutput:: 块来指定：

.. testoutput::

    2

testcode 指令的优势在于它更简单，便于指定和复制代码到剪贴板。通常，使用此指令更容易指定测试，因为输入和输出在不同的块中指定。渲染也更整洁。

注意

doctest 和 testcode 指令不应假定具有相同的命名空间。

输出:

a = 2
print(a)

关于使用 doctest 扩展的一些注意事项：

默认情况下，每个testcode和doctest块都在一个新的命名空间中运行。为了共享一个共同的命名空间，我们可以在这些块之间指定一个共同的组（在同一个.rst文件中）。例如，
```
.. doctest:: [group_name]

  >>> a = 2
```
可以跟随一些解释，然后跟随另一个代码块共享相同的命名空间
```
.. doctest:: [group_name]

  >>> print(a)
  2
```
要仅打印代码块（或输出），请使用选项 +SKIP 来指定在运行 make doctest 时不测试代码的块。
要检查Qobj输出的结果，确保忽略预期输出和实际输出之间的空格不规则性是有用的。为此，我们可以使用选项+NORMALIZE_WHITESPACE。

绘图

由于doctest指令无法渲染matplotlib图形，我们在渲染为LaTeX或HTML时使用Matplotlib的 Plot 指令。

绘图指令也可以用于doctest格式。在这种情况下，当运行doctests（通过使用>>>提示符指定所有语句来启用）时，测试还包括在绘图指令下指定的那些测试。

示例：

First we specify some data:

.. plot::

  >>> import numpy as np
  >>> x = np.linspace(0, 2 * np.pi, 1000)
  >>> x[:10] # doctest: +NORMALIZE_WHITESPACE
  array([ 0.        ,  0.00628947,  0.01257895,  0.01886842,  0.0251579 ,
          0.03144737,  0.03773685,  0.04402632,  0.0503158 ,  0.05660527])


.. plot::
  :context:

  >>> import matplotlib.pyplot as plt
  >>> plt.plot(x, np.sin(x))
  [...]

注意使用NORMALIZE_WHITESPACE选项以确保多行输出匹配。

渲染:

>>> import numpy as np
>>> x = np.linspace(0, 2 * np.pi, 1000)
>>> x[:10] 
array([ 0.        ,  0.00628947,  0.01257895,  0.01886842,  0.0251579 ,
        0.03144737,  0.03773685,  0.04402632,  0.0503158 ,  0.05660527])
>>> import matplotlib.pyplot as plt
>>> plt.plot(x, np.sin(x))
[...]

关于使用绘图指令的一些注意事项：

在绘图块中指定一个有用的参数是context，它确保代码在同一文件中的前一个绘图块的命名空间中运行。
默认情况下，每个渲染的图形在一个绘图块中（当使用:context:时）会延续到下一个块。
当context参数与reset选项一起指定为:context: reset时，命名空间将重置为一个新的命名空间，并且所有图形将被清除。
当context参数与close-figs选项一起指定为:context: reset时，命名空间将重置为一个新的命名空间，并且所有图形都会被清除。

Plot指令不能与Doctest一起使用，因为它们在同一个文件中使用时不会共享相同的命名空间。由于Plot也可以在doctest模式下使用，在代码示例既需要测试又需要渲染图形的情况下，使用Plot指令更为方便。要了解更多关于每个指令的信息，参考它们各自的页面是很有用的。