SymPy 1.13 中文文档（五十九）

原文：docs.sympy.org/latest/index.html

调试

原文：docs.sympy.org/latest/contributing/debug.html

要以调试模式启动 sympy，请设置 SYMPY_DEBUG 变量。例如在类 Unix 系统中，你可以这样做

$ SYMPY_DEBUG=True bin/isympy

或者在 Windows

设置 SYMPY_DEBUG=True > python bin/isympy

现在只需举例使用 limit() 函数。你将得到一个漂亮的打印树，对调试非常有用。

文档字符串风格指南

原文：docs.sympy.org/latest/contributing/docstring.html

通用指南

要贡献给 SymPy 的文档字符串，请完整阅读这些准则。

文档字符串（docstring）是模块、函数、类或方法定义中作为第一条语句出现的字符串文字。这样的文档字符串将成为该对象的__doc__特殊属性。

示例

这里是一个基本的文档字符串：

def fdiff(self, argindex=1):
  """
 Returns the first derivative of a Heaviside Function.

 Examples
 ========

 >>> from sympy import Heaviside, diff
 >>> from sympy.abc import x

 >>> Heaviside(x).fdiff()
 DiracDelta(x)

 >>> Heaviside(x**2 - 1).fdiff()
 DiracDelta(x**2 - 1)

 >>> diff(Heaviside(x)).fdiff()
 DiracDelta(x, 1)

 """

每个公共函数、类、方法和模块应具有描述其功能的文档字符串。对于模块中的函数或类特有的文档应位于该函数或类的文档字符串中。模块级别的文档字符串应讨论模块的目的和范围，并提供如何使用模块中的函数或类的高级示例。模块文档字符串是文件顶部的文档字符串，例如，solvers.ode 的文档字符串。

公共函数是打算由最终用户或公众使用的函数。对于公共函数，文档非常重要，因为它们将被许多人看到和使用。

另一方面，私有函数是指仅打算在 SymPy 代码中使用的函数。虽然在私有函数上撰写文档不那么重要，但在私有函数上撰写文档也有助于其他 SymPy 开发人员理解如何使用该函数。

有时不太清楚什么是公共函数，什么是私有函数。如果函数以下划线开头，则为私有函数；如果函数包含在__init__.py中，则为公共函数，但反之并非总是如此，因此有时必须根据上下文决定。总体而言，如果不确定，对函数进行文档记录总比不进行文档记录要好。

文档字符串应包含针对函数使用者的信息。特定于代码的评论或其他可能仅会分散用户注意力的注释应放在代码的注释中，而不是文档字符串中。

每个文档字符串应包含展示函数工作方式的示例。示例是文档字符串中最重要的部分。展示函数的输入和输出的单个示例可能比描述性文本段落更有帮助。

请记住，文档字符串的主要使用者是其他人类，而不是机器，因此用简单的英语描述函数的功能非常重要。同样，如何使用函数的示例应设计给人类读者，而不仅仅是为了 doctest 机制。

请记住，虽然 Sphinx 是用户消费文档字符串的主要方式，因此在编写文档字符串时（特别是对于公共函数），它是首先要考虑的平台，但并非用户消费文档字符串的唯一方式。您还可以在 IPython 中使用help()或?来查看文档字符串。例如，在使用help()时，它将显示所有私有方法的文档字符串。此外，直接阅读源代码的任何人都将看到每个文档字符串。

所有公共函数、类和方法及其相应的文档字符串应导入到 Sphinx 文档中，关于这一点的说明可以在本指南末尾找到。

格式化

文档字符串是用reStructuredText格式编写的，并由Sphinx扩展。这里是关于Quick reStructuredText的简明指南。有关使用 reStructuredText 的更详细信息可以在Sphinx 文档中找到。

为了让 Sphinx 在 HTML 文档中漂亮地呈现文档字符串，编写文档字符串时应遵循一些格式化指南：

始终在文档字符串周围使用“””三重双引号”””。如果在文档字符串中使用任何反斜杠，则使用 r”””原始三重双引号”””。
在文档字符串的关闭引号之前包含一个空行。
行不应超过 80 个字符。
请始终将类级别的文档字符串写在类定义行下面，因为在源代码中更易读。
如果类的各种方法很重要，则可以在文档字符串或示例中提及它们，但有关详细信息应在方法本身的文档字符串中。
请注意，::创建代码块，文档字符串中很少使用。任何带有示例 Python 代码的代码示例应放在 doctest 中。始终检查由 Sphinx 渲染的最终版本在 HTML 中的显示是否正确。
为了使文档字符串中的部分下划线工作得很好，使用了numpydoc Sphinx 扩展。
请始终仔细检查您的文档字符串格式是否正确：

确保您的文档字符串已导入到 Sphinx 中。
构建 Sphinx 文档（cd doc; make html）。
确保 Sphinx 没有输出任何错误。
打开 _build/html 中的页面，并确保格式正确。

部分

在 SymPy 的文档字符串中，建议函数、类和方法文档字符串按以下顺序包含以下部分：

单句总结
解释
示例
参数
另请参阅
参考资料

单句总结和示例部分是必需的每个文档字符串。如果不包括这些部分，文档字符串将无法通过审查。

不要更改这些支持的部分的名称，例如，“Examples”作为复数应该使用，即使只有一个示例。

SymPy 将继续支持NumPy 文档字符串指南中列出的所有部分标题。

标题应该用等号来下划线，长度相同。

如果某个部分不是必需的，并且对于所讨论的函数的信息是不必要的，请不要使用它。不必要的部分和杂乱的文档字符串会使函数更难理解。目标是提供理解该函数所需的最少信息。

1. 单句摘要

本节对每个文档字符串都是必需的。如果不包括该节，则文档字符串将无法通过审查。不需要为本节添加标题。

本节包含以句点结尾的一行简短句子，描述函数、类或方法的效果。

废弃警告应该直接放在单句摘要后面，以便立即通知用户。废弃警告应该以 Sphinx 指令中的deprecated形式书写：

.. deprecated:: 1.1

   The ``simplify_this`` function is deprecated. Use :func:`simplify`
   instead. See its documentation for more information.

更多细节请参见文档中的废弃。

2. 解释部分

鼓励使用本节。如果选择在文档字符串中包含一个解释部分，应该用等号来下划线，长度相同地标记为“Explanation”。

Explanation
===========

当简短的单句摘要不够详细时，本节包含了更详细的描述，说明函数、类或方法的功能。本节应用于几句或几段来澄清功能。

3. 示例部分

本节对每个文档字符串都是必需的。如果不包括该节，则文档字符串将无法通过审查。应该用等号来下划线，长度相同地标记为“Examples”（即使只有一个示例）。

Examples
========

本节包含展示函数如何工作的示例，称为 doctests。Doctests 应该足够复杂，以完全展示函数的 API 和功能，但也足够简单，使用户可以轻松理解。完美的 doctest 确切地告诉用户关于函数的一切，而不需要阅读文档字符串的其他部分。

在 doctest 之前应始终有一个空行。提供多个示例时，它们应该用空行分隔开。解释示例的注释应该在其上下都有空行。

不要将 doctest 视为测试。将它们视为恰好被测试的示例。它们应该展示函数的 API 给用户（即输入参数的样子，输出的样子，以及它的作用）。如果只想测试某些内容，请将测试添加到相关的test_*.py文件中。

你可以使用./bin/coverage_doctest.py脚本来测试文件或模块的 doctest 覆盖率。使用./bin/doctest来运行 doctest。

只有在不可能测试示例时，才应跳过其测试。如果必要，可以通过添加特殊注释来跳过示例的测试。

示例

>>> import random
>>> random.random()      
0.6868680200532414

如果示例超过 80 个字符，则应进行换行。示例应该被换行，以便它们仍然是有效的 Python 代码，使用 ... 作为 Python 提示中的继续符号。例如，来自 ODE 模块文档：

示例

>>> from sympy import Function, dsolve, cos, sin
>>> from sympy.abc import x
>>> f = Function('f')
>>> dsolve(cos(f(x)) - (x*sin(f(x)) - f(x)**2)*f(x).diff(x),
... f(x), hint='1st_exact')
Eq(x*cos(f(x)) + f(x)**3/3, C1)

这里 dsolve(cos(f(x)) - (x*sin(f(x)) - f(x)**2)*f(x).diff(x), f(x), hint='1st_exact') 太长了，因此我们在逗号后进行换行以便其可读性，并在连续行上放置 ...。如果这样做不正确，doctest 将失败。

命令的输出也可以换行。在这种情况下，不应使用 ...。doctester 自动接受换行的输出。

示例

>>> list(range(30))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
21, 22, 23, 24, 25, 26, 27, 28, 29]

在 doctest 中，像 sympy import ... 这样写入导入，而不是 import sympy 或 from sympy import *。要定义符号，请使用 from sympy.abc import x，除非名称不在 sympy.abc 中（例如，如果它具有假设），在这种情况下，使用 symbols，如 x, y = symbols('x y')。

通常应运行 ./bin/doctest 来确保您的示例正确运行，并在不正确时进行修复。

4. 参数部分

鼓励包含此部分。如果选择在文档字符串中包含参数部分，则应以等号长度下划线为标签“参数”。

Parameters
==========

如果在函数、类或方法名称后括号中列出参数，则必须包含一个参数部分。

此部分包含函数参数、关键字及其各自类型的描述。

将变量用双反引号括起来。冒号前必须有一个空格，或者如果类型不存在则可以省略冒号。对于参数类型，尽可能精确。如果不需要指定关键字参数，请使用 optional。可选关键字参数具有默认值，这些默认值显示为函数签名的一部分。它们也可以在描述中详细说明。

当参数只能假定一组固定值中的一个时，这些值可以用大括号列出，其中默认值首先出现。当两个或更多输入参数具有完全相同的类型、形状和描述时，它们可以合并。

如果参数部分格式不正确，则文档构建将呈现不正确。

如果希望包含返回部分，请将其编写为具有自己标题的单独部分。

示例

这是一个正确格式化的参数部分示例：

def opt_cse(exprs, order='canonical'):
  """
 Find optimization opportunities in Adds, Muls, Pows and negative
 coefficient Muls.

 Parameters
 ==========

 exprs : list of sympy expressions
 The expressions to optimize.
 order : string, 'none' or 'canonical'
 The order by which Mul and Add arguments are processed. For large
 expressions where speed is a concern, use the setting order='none'.

 """

5. 参见部分

鼓励包含此部分。如果选择在文档字符串中包含参见部分，则应以等号长度下划线为标签“参见”。

See Also
========

此部分包含相关函数、类和方法的列表。如果需要，相关项可以用简洁的片段描述（不需要完整句子）。如果描述跨越多行，则必须缩进后续行。

“参见”部分应仅用于引用其他 SymPy 对象。任何链接都应嵌入到文本的文档字符串中，详见参考文献部分。

不要引用 class:Classname、class:`Classname` 或 :class:`Classname` 类型，而只引用它们的类名。

示例

这是一个带有简短描述的正确格式的“参见”部分示例：

class erf(Function):
  r"""
 The Gauss error function.

 See Also
 ========

 erfc: Complementary error function.
 erfi: Imaginary error function.
 erf2: Two-argument error function.
 erfinv: Inverse error function.
 erfcinv: Inverse Complementary error function.
 erf2inv: Inverse two-argument error function.

 """

这是一个只包含名称列表的正确格式的“参见”部分示例：

class besselj(BesselBase):
  r"""
 Bessel function of the first kind.

 See Also
 ========

 bessely, besseli, besselk

 """

6. 参考文献部分

鼓励包含此部分。如果您选择在文档字符串中包含一个参考文献部分，它应该用标题“参考文献”标记，并在下方用等号长度划线。

References
==========

此部分由在前面各节中引用的参考文献列表组成。任何对其他 SymPy 对象的引用应放在“参见”部分。

参考文献部分应包括在线资源、论文引用和/或任何其他提供有关函数一般信息的印刷资源。参考文献旨在增强文档字符串，但不应要求理解它。参考文献按引用顺序编号，从一开始。

对于在线资源，只链接到免费且稳定的在线资源，如维基百科、Wolfram MathWorld 和 NIST 数学函数数字图书馆（DLMF），这些资源不太可能出现超链接失效。

论文的参考文献应按照以下顺序包括：引用编号、作者姓名、作品标题、期刊或出版物、出版年份、页码。

如果有 DOI（数字对象标识符），请在引用中包含并确保它是可点击的超链接。

示例

这是引用了印刷资源的参考文献部分示例：

References
==========

.. [1] [Kozen89] D. Kozen, S. Landau, Polynomial Decomposition Algorithms,
       Journal of Symbolic Computation 7 (1989), pp. 445-456

这是引用印刷和在线资源的参考文献部分示例：

References
==========

.. [1] Abramowitz, Milton; Stegun, Irene A., "Chapter 9," Handbook of
       Mathematical Functions with Formulas, Graphs, and Mathematical
       Tables, eds. (1965)
.. [2] Luke, Y. L., The Special Functions and Their Approximations,
       Volume 1, (1969)
.. [3] https://en.wikipedia.org/wiki/Bessel_function
.. [4] https://functions.wolfram.com/Bessel-TypeFunctions/BesselJ/

样本文档字符串

这是一个正确格式的文档字符串示例：

class gamma(Function):
  r"""
 The gamma function

 .. math::
 \Gamma(x) := \int^{\infty}_{0} t^{x-1} e^{-t} \mathrm{d}t.

 Explanation
 ===========

 The ``gamma`` function implements the function which passes through the
 values of the factorial function (i.e., $\Gamma(n) = (n - 1)!$), when n
 is an integer. More generally, $\Gamma(z)$ is defined in the whole
 complex plane except at the negative integers where there are simple
 poles.

 Examples
 ========

 >>> from sympy import S, I, pi, oo, gamma
 >>> from sympy.abc import x

 Several special values are known:

 >>> gamma(1)
 1
 >>> gamma(4)
 6
 >>> gamma(S(3)/2)
 sqrt(pi)/2

 The ``gamma`` function obeys the mirror symmetry:

 >>> from sympy import conjugate
 >>> conjugate(gamma(x))
 gamma(conjugate(x))

 Differentiation with respect to $x$ is supported:

 >>> from sympy import diff
 >>> diff(gamma(x), x)
 gamma(x)*polygamma(0, x)

 Series expansion is also supported:

 >>> from sympy import series
 >>> series(gamma(x), x, 0, 3)
 1/x - EulerGamma + x*(EulerGamma**2/2 + pi**2/12) +
 x**2*(-EulerGamma*pi**2/12 - zeta(3)/3 - EulerGamma**3/6) + O(x**3)

 We can numerically evaluate the ``gamma`` function to arbitrary
 precision on the whole complex plane:

 >>> gamma(pi).evalf(40)
 2.288037795340032417959588909060233922890
 >>> gamma(1+I).evalf(20)
 0.49801566811835604271 - 0.15494982830181068512*I

 See Also
 ========

 lowergamma: Lower incomplete gamma function.
 uppergamma: Upper incomplete gamma function.
 polygamma: Polygamma function.
 loggamma: Log Gamma function.
 digamma: Digamma function.
 trigamma: Trigamma function.
 beta: Euler Beta function.

 References
 ==========

 .. [1] https://en.wikipedia.org/wiki/Gamma_function
 .. [2] https://dlmf.nist.gov/5
 .. [3] https://mathworld.wolfram.com/GammaFunction.html
 .. [4] https://functions.wolfram.com/GammaBetaErf/Gamma/

 """

数学函数类的文档字符串

SymPy 不同寻常之处在于它还有作为数学函数的类。数学函数类的文档字符串应包括特定于此类别的详细信息，如下所述：

解释部分应包括函数的数学定义。这应该使用 LaTeX 数学公式。对于内联数学，使用 $$，对于主要定义，使用 .. math:: 来显示数学公式。公式中的变量名应与参数名匹配，并且 LaTeX 格式应与 SymPy 使用的 LaTeX 漂亮打印格式匹配。在适当的情况下，数学定义应说明其定义域，特别是如果定义域与复数不同。
如果文献中对一个函数有多种约定，请确保清楚指明 SymPy 使用的是哪种约定。
解释部分还可以包括有关函数的一些重要数学事实。这些也可以在示例部分中进行演示。数学讨论不应太长，因为用户可以查阅参考资料获取更多细节。
文档字符串不需要讨论每个实现细节，例如在“eval”方法中定义了哪些操作或在哪些点上进行评估。这些重要或有启发性的实例可以在示例部分中展示。
文档字符串应该放在类级别（紧挨着包含“class”一行的位置）。“eval” 方法不应有文档字符串。
类的私有方法，即以下划线开头的任何方法，不需要进行文档化。如果你愿意，它们仍然可以被文档化，但请注意这些文档字符串不会被导入 Sphinx 文档中，因此只有阅读代码的开发人员才能看到。因此，如果有任何非常重要的内容要提及，应该放在类级别的文档字符串中。

编写文档字符串的最佳实践

在编写文档字符串时，请遵循与编写叙述文档时相同的格式、风格和语气偏好。有关指南，请参阅编写文档的最佳实践，格式、风格和语气。

将文档字符串导入 Sphinx 文档

下面是从doc/src/modules/geometry目录中导入几段相关文档字符串到文档中的摘录：

Utils
=====

.. module:: sympy.geometry.util

.. autofunction:: intersection

.. autofunction:: convex_hull

.. autofunction:: are_similar

Points
======

.. module:: sympy.geometry.point

.. autoclass:: Point
   :members:

Lines
=====

.. module:: sympy.geometry.line

.. autoclass:: LinearEntity
   :members:

.. autoclass:: Line
   :members:

.. autoclass:: Ray
   :members:

.. autoclass:: Segment
   :members:

Curves
======

.. module:: sympy.geometry.curve

.. autoclass:: Curve
   :members:

Ellipses
========

.. module:: sympy.geometry.ellipse

.. autoclass:: Ellipse
   :members:

.. autoclass:: Circle
   :members:

Polygons
========

.. module:: sympy.geometry.polygon

.. autoclass:: Polygon
  :members:

.. autoclass:: RegularPolygon
   :members:

.. autoclass:: Triangle
   :members:

第一个命名空间设置为特定子模块（文件）使用 .. module:: 指令，然后使用 .. autoclass:: 或 .. autofunction:: 相对于该子模块（文件）导入文档字符串。其他方法要么使用所有对象的完整路径太麻烦，要么会破坏某些功能（使用 .. module:: sympy.geometry 相对于主模块导入破坏了 viewcode Sphinx 扩展）。doc/src/modules/ 中的所有文件应该使用这种格式。

交叉引用

任何引用另一个 SymPy 函数的文本都应该格式化，以便自动创建对该函数文档的交叉引用链接。这是使用 RST 交叉引用语法完成的。这里有两种不同的对象在这里有惯例：

1. 被包含在 from sympy import * 中的对象，例如，sympy.acos。

对于这些情况，使用 :obj:`~.acos()`。~ 让渲染后的 HTML 中只显示 acos 而不是完全限定名称 sympy.functions.elementary.trigonometric.acos。（这鼓励从全局 sympy 命名空间导入名称而不是特定的子模块。）. 使函数名被自动找到。（如果 Sphinx 给出多个名称找到的警告，请用完整名称替换 .。例如，:obj:`~sympy.solvers.solvers.solve()`。）添加一对括号表示这个名字是一个函数、方法或类的约定。

你也可以使用更具体的类型指示符，而不是 obj（参见 www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects）。然而，obj 总是有效的，有时候 SymPy 的名称并不是你期望的类型。例如，数学函数对象如 sin 实际上不是 Python 函数，而是 Python 类，因此 :func:`~.sin` 将不起作用。

2. 不包含在 from sympy import * 中的对象，例如，sympy.physics.vector.dynamicsymbols。

这可以是不包括在主 sympy/__init__.py 中的子模块中的公共 API 对象，例如物理子模块，或者不一定要由最终用户使用的私有 API 对象（但仍然需要文档化）。在这种情况下，你必须显示完全限定名称，因此不要使用 ~. 语法。例如，:obj:`sympy.physics.vector.dynamicsymbols()`。

你也可以编写自定义文本，链接到某些东西的文档使用以下语法 :obj:`custom text<object>`。例如，:obj:`正弦函数 <.sin>` 会产生文本“正弦函数”，链接到 sin 的文档。请注意，这里不应该使用 ~ 字符。

注意在文档字符串的另请参见部分中的引用不需要 :obj: 语法。

如果生成的交叉引用写错了，Sphinx 在构建文档时会出现错误，例如：

WARNING: py:obj reference target not found: expand

这里有一些故障排除的提示来修复错误：

确保你已经按照上述描述使用了正确的语法。
确保你拼写了函数名正确。
检查您试图交叉引用的函数是否确实包含在 Sphinx 文档中。如果没有，Sphinx 将无法为其创建引用。在这种情况下，您应将其添加到相应的 RST 文件中，如 Docstring Guidelines 中所述。
如果函数或对象未包含在from sympy import *中，则需要使用完全限定名称，例如sympy.submodule.submodule.function而不是仅仅function。
完全限定名称必须包括功能直至文件的完整子模块。例如，sympy.physics.vector.ReferenceFrame将不起作用（即使您可以在代码中以这种方式访问它）。它必须是sympy.physics.vector.frame.ReferenceFrame。
如果您要引用的内容实际上没有可以链接的地方，请勿使用:obj:语法。而是使用双反引号将其标记为代码。不能链接到的示例包括 Python 内置函数如int或NotImplementedError，SymPy 外的其他模块的函数如matplotlib.plot，以及特定于手头文本的变量或参数名称。一般来说，如果无法访问对象作为sympy.something.something.object，则无法交叉引用，不应使用:obj:语法。
如果您正在使用类型特定标识符之一，比如:func:，请确保其类型正确。:func:仅适用于 Python 函数。对于类，请使用:class:，对于类的方法，请使用:method:。一般来说，建议使用:obj:，因为这适用于任何类型的对象。
如果无法使交叉引用语法工作，请继续提交原样拉取请求，并请求审阅者帮助。

您可能还会看到类似以下的错误：

WARNING: more than one target found for cross-reference 'subs()':
sympy.core.basic.Basic.subs, sympy.matrices.matrixbase.MatrixBase.subs,
sympy.physics.vector.vector.Vector.subs,
sympy.physics.vector.dyadic.Dyadic.subs

例如，使用:obj:`~.subs` 。这意味着.不足以找到函数，因为 SymPy 中有多个名为subs的名称。在这种情况下，您需要使用完全限定名称。您仍然可以使用~来在最终文本中缩短它，例如:obj:`~sympy.core.basic.Basic.subs` 。

Python 文件中警告的行号是相对于 docstring 顶部而不是文件本身的。行号通常不完全正确，因此您通常需要搜索 docstring 以找到警告所指的部分。这是由于 Sphinx 中的一个 bug。

文档风格指南

原文链接：docs.sympy.org/latest/contributing/documentation-style-guide.html

一般指南

文档是开源项目中最受重视的方面之一。文档教会用户和贡献者如何使用项目，如何贡献以及开源社区内的行为规范。但根据 GitHub 的开源调查，不完整或令人困惑的文档是开源项目中最常见的问题。本风格指南旨在改变这一现状。

本风格指南的目的是为 SymPy 社区提供一套在编写 SymPy 文档时可以利用和遵循的风格和格式指南。遵循本风格指南提供的准则将为 SymPy 的文档带来更大的一致性和清晰度，支持其成为一个功能齐全的开源计算代数系统（CAS）的使命。

SymPy 文档位于docs.sympy.org，由源代码中的文档字符串和专用叙述文档文件在doc/src 目录中生成。两者均采用Sphinx扩展的reStructuredText格式。

文档存储在doc/src 目录中，以及嵌入在 Python 源代码中的文档字符串都由 Sphinx 及其各种扩展处理。这意味着文档源格式由文档处理工具指定。SymPy 文档风格指南提供了编写 SymPy 文档的基本要素以及我们相对于这些文档处理工具指定的任何风格偏差。以下列出了处理工具：

reStructuredText：嵌入在 Python 代码中的叙述文档文件和文档字符串遵循 reStructuredText 格式。本文档未描述的高级功能可在docutils.sourceforge.io/rst.html找到。
Sphinx：Sphinx 包含了 reStructuredText 规范的其他默认特性，详情请见：www.sphinx-doc.org/en/master。
由 Sphinx 包含的扩展：
- sphinx.ext.autodoc：处理 Python 源代码文件，以自动生成包含应用程序编程接口（API）的页面。查看本文档中关于调用 autodoc 指令的部分以开始使用。更多信息请参阅：www.sphinx-doc.org/en/master/usage/extensions/autodoc.html。
- sphinx.ext.graphviz: 提供一个指令用于添加 Graphviz 图形。详见 www.sphinx-doc.org/en/master/usage/extensions/graphviz.html。
- sphinx.ext.mathjax: 使 LaTeX 写的数学公式在文档的 HTML 版本中使用 MathJax 显示。更多信息请参阅：www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax。对文档源格式无影响。
- sphinx.ext.linkcode: 导致链接到源代码的链接指向 Github 上的相关文件。详见 www.sphinx-doc.org/en/master/usage/extensions/linkcode.html。对文档源格式无影响。
我们启用的不随 Sphinx 一起提供的 Sphinx 扩展有：
- numpydoc: 处理用numpydoc格式编写的文档字符串，详见 numpydoc.readthedocs.io/en/stable/。我们建议在本文档中使用 numpydoc 格式的子集功能。（请注意，我们目前使用的是 SymPy 源代码中包含的旧版本 numpydoc 的修改分支。）
- sphinx_math_dollar: 允许使用美元符号来界定数学公式，而不是 reStructuredText 的指令（例如， $a²$ 而不是 :math:`a²`）。详见 www.sympy.org/sphinx-math-dollar/。
- matplotlib.sphinxext.plot_directive: 提供指令以在 reStructuredText 中包含由 matplotlib 生成的图表。详见 matplotlib.org/devel/plot_directive.html。

所有上述处理工具支持的功能都可以在 SymPy 文档中使用，但本样式指南将覆盖上述任何建议。请注意，我们不遵循 PEP 257 或 www.python.org 的文档建议。

如果您是第一次为 SymPy 做贡献，请阅读我们的贡献简介页面以及本指南。

文档类型

SymPy 文档的主要位置有四个：

SymPy 网站 www.sympy.org/

SymPy 网站的主要功能是向用户和开发人员宣传软件。它还作为指向网络上其他相关资源的初始位置。SymPy 网站提供有关 SymPy 及其获取方式的基本信息，以及用于向用户宣传的示例，但没有技术文档。源文件位于 SymPy 网页目录。适用于网站的内容包括：

SymPy 和 SymPy 社区的一般描述
主要软件功能的解释/演示
列出了使用 SymPy 的其他主要软件
用户入门信息（下载和安装说明）
开发者入门信息
用户可以获取 SymPy 使用帮助和支持的地方
SymPy 的最新消息

SymPy 文档 docs.sympy.org

这是用户学习如何使用 SymPy 的主要位置。它包含了 SymPy 的教程以及所有模块的技术文档。源文件托管在主 SymPy 仓库的doc 目录，使用Sphinx 站点生成器构建，并自动上传到 docs.sympy.org 网站。从 docs 目录中不同的源文件生成两种主要类型的页面：

叙述页面：reStructuredText 文件，对应手动编写的文档页面。例如，教程 RST 文件。一般来说，如果您的文档不是 API 文档，它应该属于叙述页面。
API 文档页面：reStructuredText 文件，包含生成应用程序接口文档的指令。这些文档是从 SymPy Python 源代码自动生成的。

SymPy 源代码 github.com/sympy/sympy

大多数函数和类都包含作为 docstring 形式的内部文档，其中解释了函数并包含称为 doctest 的示例。这些 docstring 的目的是解释该类或函数的 API。这些 doctest 示例作为测试套件的一部分进行测试，以确保它们始终产生其所说的输出。这里是一个示例 docstring。大多数 docstring 也会自动包含在上述 Sphinx 文档中，以便它们出现在 SymPy 文档网站上。这是 SymPy 网站上相同的相同 docstring。这些 docstring 采用特定的格式，以便 Sphinx 能够正确渲染它们用于文档网站。SymPy 源码中所有的技术文档都以源代码注释的形式存在，尽管这通常不构成实质性内容，也不会显示在文档网站上。

SymPy Wiki github.com/sympy/sympy/wiki

SymPy Wiki 可以由任何人在无需审核的情况下进行编辑。其中包含各种类型的文档，包括：

高级开发者文档（例如：github.com/sympy/sympy/wiki/Args-Invariant）
发布说明（例如：github.com/sympy/sympy/wiki/Release-Notes-for-1.5）
各种不同贡献者添加的页面

叙述文档指南

全面的文档，或者非围绕 API 参考的文档，应作为 Sphinx 文档中的叙述性文档撰写（位于doc/src 目录）。叙述文档不驻留在 Python 源文件中，而是作为独立的 restructured 文件存在于 doc/src 目录中。SymPy 的叙述性文档定义为教用户如何使用 SymPy 的集体文档、教程和指南。参考文档应放在文档字符串中，并通过 autodoc 拉入 RST。RST 本身应只包含不是单个特定函数参考的叙述式文档。

使用 Markdown 撰写文档

叙述性文档可以使用 Restructured Text（.rst）或 Markdown（.md）编写。Markdown 文档使用MyST。有关如何在 Markdown 中撰写文档的更多信息，请参阅此指南。Markdown 仅支持叙述性文档。文档字符串应继续使用 RST 语法。本样式指南中不特定于 RST 语法的任何部分仍然适用于 Markdown 文档。

编写文档的最佳实践

撰写文档时，请遵循这些格式化、样式和语调偏好。

格式首选项

为了使 SymPy 网站上的数学和代码正确渲染，请遵循这些格式化准则。

数学

由美元符号 $ _ $ 包围的文本将被渲染为 LaTeX 数学公式。任何应作为 LaTeX 数学公式显示的文本都应写为 $math$ 。在文档的 HTML 版本中，MathJax 将渲染这些数学公式。

示例

The Bessel $J$ function of order $\nu$ is defined to be the function
satisfying Bessel’s differential equation. 
```  #### LaTeX 推荐

+   如果文档字符串包含任何 LaTeX 代码，请确保将其设置为“原始”状态。有关详细信息，请参见文档字符串格式化部分。

+   如果不确定如何渲染某些内容，可以使用 SymPy `latex()` 函数。但请确保删除不重要的部分（如下面的项目符号）。

+   避免不必要的 `\left` 和 `\right`（但在必要时确保使用它们）。

+   避免不必要的 `{}`。（例如，写 `x²` 而不是 `x^{2}`。）

+   使用空格使方程最易于阅读。

+   始终检查最终呈现效果，确保符合预期。

+   HTML 文档生成不会因为存在无效的数学而失败，而是会在页面上显示为错误。但是，在 GitHub Actions 上拉取请求时运行的 LaTeX PDF 构建将失败。如果 CI 中的 LaTeX PDF 构建失败，则可能存在 LaTeX 数学的问题。

**示例**

正确：

```py
\int \sin(x)\,dx

不正确：

\int \sin{\left( x\right)}\, dx

要了解如何在 LaTeX 中编写数学更深入的资源，请参见：

代码

应该原样打印的文本，例如代码，应该用一对双反引号 like this 包围起来。

示例

To use this class, define the ``_rewrite()`` and ``_expand()`` methods.

有时一个变量在数学和代码中是相同的，并且甚至可以出现在同一段落中，这使得很难知道它应该格式化为数学还是代码。如果所讨论的句子涉及数学，则应使用 LaTeX，但如果句子讨论的是 SymPy 实现，则应使用代码。

一般来说，可以根据所讨论的变量在代码和数学中是否以不同方式呈现来判断。例如，希腊字母 α 在代码中写作 alpha，在 LaTeX 中写作 $\alpha$ 。原因是 $\alpha$ 不能在涉及 Python 代码的上下文中使用，反之 alpha 在数学上下文中也是不正确的，因为它不能显示为希腊字母 (α)。

示例

class loggamma(Function):
  r"""
 The ``loggamma`` function implements the logarithm of the gamma
 function (i.e, $\log\Gamma(x)$).

 """

在函数名称后列出的参数中，书面文本中应使用斜体，使用 Sphinx 强调，像 *this*。

示例

def stirling(n, k, d=None, kind=2, signed=False):
  """
 ...

 The first kind of Stirling number counts the number of permutations of
 *n* distinct items that have *k* cycles; the second kind counts the
 ways in which *n* distinct items can be partitioned into *k* parts.
 If *d* is given, the "reduced Stirling number of the second kind" is
 returned: $S^{d}(n, k) = S(n - d + 1, k - d + 1)$ with $n \ge k \ge d$.
 This counts the ways to partition $n$ consecutive integers into $k$
 groups with no pairwise difference less than $d$.

 """

请注意，在上述示例中，n 和 k 的第一个实例是指 stirling 函数的输入参数。因为它们是 Python 变量，但也是单独列出的参数，所以它们被格式化为斜体参数。(n) 和 (k) 的最后一个实例讨论的是数学表达式，因此它们被格式化为数学。

如果一个变量是代码，但也是单独写的参数，参数格式应优先，并且应该用斜体显示。然而，如果一个参数出现在一个较大的代码表达式中，则应在双反引号内作为代码呈现。如果一个变量只是代码而不是参数，则应在双反引号内作为代码呈现。

请注意，与 SymPy 中的参数或代码不同，对 SymPy 中其他函数的引用处理方式不同。如果某些内容引用了 SymPy 中的另一个函数，则应使用交叉引用 reStructuredText 语法。有关更多信息，请参阅交叉引用部分。

标题

在 reStructuredText 文件中，通过使用至少与文本一样长的标点符号在标题下方（可选地上方）创建章节标题。

通常情况下，某些字符不分配标题级别，因为结构是从标题的连续性中确定的。但是，对于 SymPy 的文档，这里建议的惯例是：

=== 与上划线：标题（顶级标题）

=== 标题 1

--- 标题 2

^^^ 标题 3

~~~ 标题 4

""" 标题 5

样式偏好

拼写和标点

SymPy 所有叙述性写作均遵循美国拼写和标点符号标准。例如，“color”优先于“colour”，逗号应放在引号内。

示例

If the ``line_color`` aesthetic is a function of arity 1, then the coloring
is a function of the x value of a point.

The term "unrestricted necklace," or "bracelet," is used to imply an object
that can be turned over or a sequence that can be reversed.

如果存在关于单词拼写的歧义，例如以人名命名的函数，应参考实际 SymPy 函数的拼写。

例如，切比雪夫多项式以帕夫努蒂·利沃维奇·切比雪夫命名，其名称有时从俄语转写为以“T”拼写，但在 SymPy 中应始终拼写为“Chebyshev”以指代 SymPy 函数。

示例

class chebyshevt(OrthogonalPolynomial):
  r"""
 Chebyshev polynomial of the first kind, $T_n(x)$
 ...

 """

大写格式

在所有 SymPy 标题中首选使用大写标题格式。

示例

What is Symbolic Computation?
-----------------------------

语调偏好

在 SymPy 所有文档中，请使用以下格式：

现在时态（例如，在接下来的部分，我们将学习…）
第一人称包含复数（例如，我们以长方式完成了此操作，但现在可以尝试以短方式进行…）
使用通用代词“you”而不是“one”。或者使用“读者”或“用户”。（例如，您可以通过以下方法访问此功能… 用户然后可以通过以下方式访问此功能…）
使用性别中立代词“they”而不是“he”或“she”。（例如，一个好的文档字符串告诉用户他们需要知道的一切。）

避免使用“显然”，“容易”，“简单”，“只是”或“直接”等多余或轻视的词语。

避免使用不友好或基于评判的短语，如“那是错误的”。而是使用友好和包容性语言，如“一个常见的错误是…”

避免多余的短语，如“我们只需要再做一件事。”

弃用政策

原文：docs.sympy.org/latest/contributing/deprecations.html

此页面概述了 SymPy 在执行弃用时的政策，并描述了开发人员应采取的适当步骤。

SymPy 中所有当前活动弃用的列表可以在当前活动弃用列表中找到。

什么是弃用？

弃用是以允许用户更新其代码的方式进行不向后兼容的更改。已弃用的代码仍然像以前一样工作，但每当有人使用它时，屏幕上会打印一条警告，指示将来版本中将删除 SymPy 的内容，并指示用户应使用的替代方案。

这使得用户有机会更新他们的代码而不会完全中断。这还使得 SymPy 有机会向用户提供关于如何更新其代码的信息性消息，而不是使他们的代码简单地报错或开始提供错误答案。

首先尽量避免不向后兼容的更改

不轻易进行不向后兼容的 API 更改。任何向后兼容性断裂都意味着用户需要修复他们的代码。每当你想进行破坏性更改时，都应考虑这是否值得用户付出这样的痛苦。每次 SymPy 发布新版本时，用户都必须更新他们的代码以匹配新的 API，这会让他们对该库感到沮丧，并可能寻找更稳定的替代方案。请考虑您想要的行为是否可以以与现有 API 兼容的方式完成。新的 API 并不一定需要完全取代旧的 API。有时旧的 API 可以与更新、设计更好的 API 并存而不被移除。例如，更新后的 solveset API 旨在作为旧的 solve API 的优秀替代品，但旧的solve()函数仍然完整且仍然受支持。

当添加新功能时，尝试在意 API 设计是很重要的。试着考虑一个函数未来可能做什么，并设计 API 以便它可以在不进行破坏性更改的情况下实现。例如，如果您向对象A.attr添加属性，那么以后将无法将该属性转换为方法A.attr()以便它可以接受参数，除非以不向后兼容的方式进行。如果您对新功能的 API 设计不确定，一种选择是将新功能标记为显式私有或实验性。

话虽如此，可能决定必须以某种不兼容的方式更改 SymPy 的 API。更改 API 的原因可能包括：

现有的 API 令人困惑。
API 中存在不必要的冗余。
现有的 API 限制了可能性。

因为 SymPy 的核心用例之一是作为库可用，我们非常严肃地对待 API 的破坏性变更。每当需要 API 破坏性变更时，应采取以下步骤：

与社区讨论 API 更改。确保改进的 API 确实更好，并且值得破坏。正确地设置 API 非常重要，这样我们就不需要再次破坏 API 来“修复”它。
如果可能的话，废弃旧的 API。如何进行技术步骤的描述见下文。
记录更改，以便用户知道如何更新他们的代码。所需添加的文档描述见下文。

何时需要废弃一个改变？

在考虑一个改变是否需要废弃时，必须考虑两件事：

更改是否向后不兼容？
行为是否在改变公共 API？

如果用户代码在更改后无法正常工作，则该更改是向后不兼容的。

什么算是“公共 API”需要具体情况具体分析。关于 SymPy 中什么构成和不构成公共 API 的确切规则尚未完全编码。清理公共和私有 API 之间的区别，以及参考文档中的分类，目前仍然是 SymPy 的一个开放问题。

这里有些东西构成了公共 API。注意：这些只是一般指导方针。这个列表并非详尽无遗，总有例外情况。

公共 API

函数名。
关键字参数名称。
关键字参数默认值。
位置参数顺序。
子模块名称。
定义函数所使用的数学约定。

还有一些通常不是公共 API 的东西，因此不需要废弃以进行更改（再次强调，这个列表仅是一般指导方针）。

非公共 API

表达式的精确形式。一般来说，函数可能被更改为返回同一表达式的不同但数学上等价的形式。这包括函数返回以前无法计算的值。
私有的函数和方法，即仅用于内部。这些东西通常应该以下划线 _ 前缀，尽管这种约定目前在 SymPy 代码库中并不普遍遵循。
任何明确标记为“实验性”的东西。
先前数学上不正确的行为更改（一般而言，修复错误不被视为破坏性更改，因为尽管有这种说法，但 SymPy 中的错误不是特性）。
在最近的发布之前添加的任何内容。尚未发布的代码不需要被废弃。如果要更改新代码的 API，最好在发布之前进行，以便未来的发布不需要废弃。

注意：参考文档包括参考文档中的公共和私有 API 函数，许多应包括在内的函数未包括在其中，或者根本没有文档化，因此这不应用于确定某些内容是公共的还是私有的。

如果不确定，即使可能实际上并非“公共 API”，也没有害处废弃某些内容。

废弃的目的

废弃有几个目的：

允许现有代码继续工作一段时间，让人们有机会升级 SymPy，而不立即修复所有废弃问题。
警告用户其代码将来会在某个版本中断。
告知用户如何修复其代码，以使其在未来版本中继续工作。

所有废弃警告应该是用户可以通过更新其代码来移除的。应避免无条件触发废弃警告，即使使用了“正确”的新 API。

这也意味着所有废弃的代码必须有一个完全可用的替代方案。如果没有办法让用户更新其代码，那么这意味着相关 API 尚未准备好废弃。废弃警告应通知用户如何更改其代码，以使其在同一版本的 SymPy 中继续工作，以及所有未来版本，如果可能的话，还包括之前的版本。参见下文。

废弃始终应该

允许用户在废弃期间继续使用现有的 API（附有警告，可以通过warnings.filterwarnings进行消除）。
允许用户始终修复其代码，以防止出现警告。
用户修复其代码后，废弃的代码移除后应继续工作。

第三点很重要。我们不希望“新”方法在废弃期结束时本身导致另一个 API 断裂。这样做将完全抵消废弃的目的。

当技术上不可能废弃时

在某些情况下，技术上不可能进行符合上述三条规则的废弃。此类性质的 API 更改应该被认为是最重要的，因为它们将立即破坏用户的代码而不发出警告。还应考虑到用户支持多个 SymPy 版本的容易程度，一个带有更改，一个不带有更改。

如果决定更改仍然值得，有两种选择：

立即进行不可废弃的更改，不发出警告。这将打破用户代码。
警告代码将来会更改。在有版本引入破坏性更改之前，用户将无法修复其代码，但他们至少会意识到即将进行的更改。

应该根据具体情况决定采取哪种方式。

废弃应该持续多久？

在首次主要发布时，弃用应至少持续 1 年。这只是最短期限：弃用可以保持更长时间。如果某项变更对用户的迁移特别困难，则应延长弃用期限。对于不会对维护造成重大负担的已弃用功能，期限也可以延长。

弃用期限策略基于时间而非发布。原因有几点：首先，SymPy 没有定期的发布计划。有时一年内可能发布多个版本，有时可能只有一个版本。基于时间的策略确保用户有充足的机会更新其代码，无论发布频率如何。

其次，SymPy 不采用严格的语义化版本方案。SymPy 的 API 表面和贡献数量都足够大，几乎每个主要版本都会在某些子模块中进行一些弃用和不向后兼容的更改。将这些编码到版本号中几乎是不可能的。开发团队也不会在极端情况下向之前的主要版本回溯更改。因此，基于时间的弃用方案比基于版本的方案更符合 SymPy 的发布模型。

最后，基于时间的方案消除了通过提前发布来“篡改”弃用期限的任何诱惑。开发人员加速移除弃用功能的最佳方法是尽早发布包含弃用的版本。

如何弃用代码

检查清单

这里是进行弃用的检查清单。详细信息请参见下文。

与社区讨论不向后兼容的更改。根据上述讨论确保更改真的值得。
从代码库中的所有地方（包括 doctest 示例）删除所有弃用代码的实例。
在代码中添加sympy_deprecation_warning()。
- 为sympy_deprecation_warning()编写描述性消息。确保消息解释了何为弃用以及替换方式。消息可以是多行字符串并包含示例。
- 将deprecated_since_version设置为sympy/release.py中的版本（不含.dev）。
- 将active_deprecations_target设置为active-deprecations.md文件中使用的目标。
- 确保stacklevel设置为正确的值，以便弃用警告显示用户的代码行。
- 确认控制台中的弃用警告显示效果良好。
在相关文档字符串的顶部添加一个.. deprecated:: <version>的注释。
在doc/src/explanation/active-deprecations.md文件中添加一个部分。
- 在节标题之前添加交叉引用目标(deprecation-xyz)=（与上述的active_deprecations_target使用的引用相同）。
- 解释什么是已弃用以及应该替换的内容。
- 解释为什么给定的事物已弃用。
添加一个使用warns_deprecated_sympy()的测试，测试已弃用警告是否正确发出。此测试应该是代码中唯一使用已弃用功能的地方。
运行测试套件以确保上述测试正常工作，并且没有其他代码使用了已弃用的代码，否则测试将失败。
在您的 PR 中，为弃用添加一个BREAKING CHANGE条目到发布说明中。
一旦合并了 PR，请手动将更改添加到维基上的“向后兼容性断裂和弃用”部分的发布说明中。

将弃用添加到代码中

所有弃用应该使用sympy.utilities.exceptions.sympy_deprecation_warning()。如果整个函数或方法已弃用，可以使用sympy.utilities.decorator.deprecated()装饰器。deprecated_since_version和active_deprecations_target标志是必需的。请勿直接使用SymPyDeprecationWarning类来发出弃用警告。有关详细信息，请参阅sympy_deprecation_warning()的文档字符串。请参见下面的弃用文档以获取示例。

为已弃用的行为添加一个测试。使用sympy.testing.pytest.warns_deprecated_sympy()上下文管理器。

from sympy.testing.pytest import warns_deprecated_sympy

with warns_deprecated_sympy():
    <deprecated behavior>

注意

warns_deprecated_sympy仅供 SymPy 测试套件内部使用。SymPy 的用户应直接使用warnings模块来过滤 SymPy 的弃用警告。请参阅静音 SymPy 弃用警告。

这有两个目的：测试警告是否正确发出，并测试已弃用的行为是否仍然有效。

如果要测试多个事物并断言每个事物都发出警告，则对每个事物使用单独的 with 块：

with warns_deprecated_sympy():
    <deprecated behavior1>
with warns_deprecated_sympy():
    <deprecated behavior2>

这应该是唯一使用废弃行为的代码库和测试套件部分。其他所有内容都应更改为使用新的、非废弃的行为。SymPy 测试套件配置为，如果在任何地方发出SymPyDeprecationWarning，除了在warns_deprecated_sympy()块中，都将失败。您不应在废弃测试之外的任何地方使用此函数或warnings.filterwarnings(SymPyDeprecationWarning)。这包括废弃函数的文档示例。废弃函数的文档应该只有一个指向非废弃替代方法的注释。如果要在 doctest 中显示废弃函数，请使用# doctest: +SKIP。唯一的例外是您可以使用ignore_warnings(SymPyDeprecationWarning)来防止同一警告触发两次，即如果一个废弃函数调用另一个发出相同或类似警告的函数。

如果不可能在某处移除废弃的行为，则说明该行为尚未准备好被废弃。考虑到用户可能因为相同的原因无法替换废弃的行为。

记录废弃信息

所有废弃信息都应进行记录。每个废弃信息都需要在三个主要位置进行记录：

sympy_deprecation_warning() 警告文本。本文允许较长，以描述废弃情况，但不应超过一段。警告文本的主要目的是通知用户如何更新其代码。警告文本不应讨论为何功能被废弃或不必要的内部技术细节。此类讨论可放入下面提到的其他部分。不要在消息中包含已提供给sympy_deprecation_warning()关键字参数的元数据信息，如版本号或活动废弃文档的链接。请记住，警告文本将以纯文本形式显示，因此不要在文本中使用 RST 或 Markdown 标记。代码块应有明确的换行来使其易于阅读。警告消息中的所有文本应包装到 80 个字符，除了不能包装的代码示例。

始终包含消息中废弃内容的完整上下文。例如，写“废弃了 abc 关键字到 func()”而不仅仅是“废弃了 abc 关键字”。这样，如果用户有一行较长的代码正在使用废弃功能，他们可以更容易地看到确切引发警告的部分。

在相关文档字符串中添加一个弃用说明。这应该使用deprecated Sphinx 指令。使用语法.. deprecated:: <version>。如果整个函数都已弃用，则应将其放置在文档字符串顶部，正好在第一行下面。否则，如果只有部分函数已弃用（例如，单个关键字参数），则应将其放置在讨论该功能部分的文档字符串附近，例如在参数列表中。

弃用文本应简短（不超过一个段落），解释何处已弃用以及用户应该使用什么代替。如果愿意，可以在此处使用与sympy_deprecation_warning()相同的文本。确保使用 RST 格式，包括与新函数相关的交叉引用，以及到active-deprecations.md文档中的更长描述的交叉引用（参见下文）。

如果功能的文档与替换功能的文档相同（即，弃用只是对函数或参数的重命名），则可以用“请参阅<新功能>的文档”等备注替换其余文档。否则，应保留弃用功能的文档不变。

这里有一些（虚构的）例子：

@deprecated("""\
The simplify_this(expr) function is deprecated. Use simplify(expr)
instead.""", deprecated_since_version="1.1",
active_deprecations_target='simplify-this-deprecation')
def simplify_this(expr):
  """
 Simplify ``expr``.

 .. deprecated:: 1.1

 The ``simplify_this`` function is deprecated. Use :func:`simplify`
 instead. See its documentation for more information. See
 :ref:`simplify-this-deprecation` for details.

 """
    return simplify(expr)

def is_this_zero(x, y=0):
  """
 Determine if x = 0.

 Parameters
 ==========

 x : Expr
 The expression to check.

 y : Expr, optional
 If provided, check if x = y.

 .. deprecated:: 1.1

 The ``y`` argument to ``is_this_zero`` is deprecated. Use
 ``is_this_zero(x - y)`` instead. See
 :ref:`is-this-zero-y-deprecated` for more details.

 """
    if y != 0:
        sympy_deprecation_warning("""\
The y argument to is_zero() is deprecated. Use is_zero(x - y) instead.""",
            deprecated_since_version="1.1",
            active_deprecations_target='is-this-zero-y-deprecation')
    return simplify(x - y) == 0

应该将弃用功能的更长描述添加到文档中列出所有当前活动弃用的页面（位于doc/src/explanation/active-deprecations.md中）中。

这个页面是您可以深入了解弃用技术细节的地方。在这里，您还应列出为何某个功能被弃用的原因。您可以链接到相关问题、拉取请求和邮件列表讨论有关弃用的内容，但这些讨论应该总结，以便用户可以简要了解弃用的基本思想，而不必阅读旧讨论的页面。您还可以在这里提供在sympy_deprecation_warning()消息或.. deprecated::文本中无法容纳的更长示例。

每个弃用都应该有一个交叉引用目标（使用 (target-name)= 放在章节标题上方），以便相关文档字符串中的 .. deprecated:: 笔记可以引用它。这个目标还应该传递给 sympy_deprecation_warning() 或 @deprecated 的 active_deprecations_target 选项。这将自动在警告消息的文档中链接到页面。目标名称应包含“deprecation”或“deprecated”这些词（Sphinx 中目标名称是全局的，因此目标名称在整个文档中必须是唯一的）。

章节标题名称应该是被弃用的内容，应该是相应版本的三级标题（通常应添加到文件顶部）。

如果多个弃用彼此相关，则可以共享本页的单个部分。

如果弃用的函数未包含在顶级 sympy/__init__.py 中，请确保清楚指出对象所属的子模块。如果引用了 Sphinx 模块参考文档中的任何内容，请进行交叉引用，例如 {func}`~.func_name`。

注意这里的示例很有帮助，但通常不应使用文档测试来显示已弃用的功能，因为这将引发弃用警告并使文档测试失败。相反，您可以使用 # doctest: +SKIP，或者将示例显示为代码块而不是文档测试。

这里是对应于（虚构的）上述示例的示例：
```
(simplify-this-deprecation)=
### `simplify_this()`

The `sympy.simplify.simplify_this()` function is deprecated. It has been
replaced with the {func}`~.simplify` function. Code using `simplify_this()`
can be fixed by replacing `simplfiy_this(expr)` with `simplify(expr)`. The
behavior of the two functions is otherwise identical.

This change was made because `simplify` is a much more Pythonic name than
`simplify_this`. 
```
```
(is-this-zero-y-deprecation)=
### `is_this_zero()` second argument
The second argument to {func}`~.is_this_zero()` is deprecated. Previously
`is_this_zero(x, y)` would check if x = y. However, this was removed because
it is trivially equivalent to `is_this_zero(x - y)`. Furthermore, allowing
to check $x=y$ in addition to just $x=0$ is is confusing given the function
is named "is this zero".

In particular, replace

```py

is_this_zero(expr1, expr2)

```py

with

```py

is_this_zero(expr1 - expr2)

```py 
```

除了上述示例，SymPy 代码库中还有数十个现有弃用的示例，可以通过在 SymPy 代码库中搜索 sympy_deprecation_warning 找到。

发布说明条目

在拉取请求中，在发布说明部分记录破坏性更改使用 BREAKING CHANGE。

一旦 PR 合并，您还应将其添加到即将发布的版本的“向后兼容性中断和弃用”部分的发布说明中。这需要手动完成，除了机器人的更改之外。参见 github.com/sympy/sympy/wiki/Writing-Release-Notes#user-content-backwards-compatibility-breaks-and-deprecations

每当在其弃用期后完全移除已弃用的功能时，这也需要标记为 BREAKING CHANGE 并添加到“向后兼容性中断和弃用”部分的发布说明中。

SymPy-1-13-中文文档-五十九-