文档风格指南

一般指南

文档是开源项目最受重视的方面之一。文档教导用户和贡献者如何使用项目、如何贡献以及开源社区中的行为准则。但根据 GitHub 的 开源调查，不完整或含糊的文档是开源中最常见的问题。本风格指南旨在改变这一点。

本风格指南的目的是为 SymPy 社区提供一套风格和格式指南，以便在编写 SymPy 文档时可以利用和遵循这些指南。遵循本风格指南中提供的指南将为 SymPy 的文档带来更大的一致性和清晰度，支持其成为功能齐全的开源计算机代数系统 (CAS) 的目标。

位于 docs.sympy.org 上的 SymPy 文档是从源代码中的文档字符串和 doc/src 目录 中的专用叙述性文档文件生成的。两者都是用 reStructuredText 格式编写的，并由 Sphinx 扩展。

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

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

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

文档类型

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

SymPy 网站 https://www.sympy.cn/

SymPy 网站的主要功能是向用户和开发人员宣传该软件。它还用作将观众引导到网上其他相关资源的初始位置。SymPy 网站提供有关 SymPy 以及如何获取它的基本信息，以及用于向用户宣传的示例，但它没有技术文档。源文件位于 SymPy 的 网页目录 中。适合网站的项目包括

  • 对 SymPy 和 SymPy 社区的一般描述

  • 主要软件功能的解释/演示

  • 使用 SymPy 的其他主要软件的清单

  • 用户入门信息（下载和安装说明）

  • 开发人员入门信息

  • 用户可以在哪里获取有关使用 SymPy 的帮助和支持

  • 关于 SymPy 的新闻

SymPy 文档 https://docs.sympy.cn

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

  • 叙述性页面：对应于 Python 源代码中不存在的手动编写的文档页面的 reStructuredText 文件。例如 教程 RST 文件。一般来说，如果您的文档不是 API 文档，则它应位于叙述性页面中。

  • API 文档页面：包含指令的 reStructuredText 文件，这些指令生成应用程序编程接口文档。这些页面由 SymPy Python 源代码自动生成。

SymPy 源代码 https://github.com/sympy/sympy

大多数函数和类都包含在其中编写的文档，以文档字符串的形式，解释函数并包含称为 doctest 的示例。这些文档字符串的目的是解释该类或函数的 API。doctest 示例作为测试套件的一部分进行测试，因此我们可以知道它们始终生成它们声明生成的输出。以下是一个 文档字符串示例。大多数文档字符串也会自动包含在上面的 Sphinx 文档中，以便它们出现在 SymPy 文档网站上。以下是该 same docstring 在 SymPy 网站上的显示方式。文档字符串的格式以特定方式编写，以便 Sphinx 可以为 docs 网站正确地渲染它们。SymPy 源代码都包含以源代码注释形式编写的稀疏技术文档，尽管这通常不构成任何实质内容，也不在文档网站上显示。

SymPy Wiki https://github.com/sympy/sympy/wiki

任何人都可以在没有审查的情况下编辑 SymPy Wiki。它包含各种类型的文档，包括

叙述性文档指南

广泛的文档或以 API 参考为中心的文档应作为 Sphinx 文档中的叙述性文档编写（位于 doc/src 目录 中）。叙述性文档不驻留在 Python 源文件中，而是作为独立的结构化文件位于 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^2 而不是 x^{2}。）

  • 使用空白以使方程最易于阅读。

  • 始终检查最终渲染，以确保它按预期显示。

  • 如果存在无效的数学公式，HTML 文档构建不会失败，而是在页面上显示为错误。但是，PDF 构建（在拉取请求上通过 GitHub Actions 运行）将失败。如果 LaTeX PDF 构建在 CI 上失败，则很可能存在 LaTeX 数学公式问题。

示例

正确

\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 代码的上下文中，因为它不是有效的 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 中的另一个函数，则应使用交叉引用 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"。或者使用 "the reader" 或 "the user"。（例如，您可以通过以下方式访问此函数……用户可以访问此函数……）

  • 使用中性代词 "they" 代替 "he" 或 "she"。（例如，一个好的文档字符串会告诉用户他们需要知道的一切。）

避免使用 "obviously"、"easily"、"simply"、"just" 或 "straightforward" 等多余或贬低性的词语。

避免使用 "That is wrong" 等不友好或带有判断性的短语。相反，请使用友好和包容性的语言，例如 "A common mistake is…"。

避免使用多余的短语，例如 "we just have to do one more thing"。