文档风格指南

一般指南

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

本风格指南的目的是为 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.org/

SymPy 网站的主要功能是向用户和开发者宣传该软件。它还作为引导观众访问网络上其他相关资源的首要位置。SymPy 网站提供了关于 SymPy 的基本信息以及如何获取它的方法，还有向用户宣传的示例，但它没有技术文档。源文件位于 SymPy 的 网页目录 中。适合网站的内容包括：

  • SymPy 及其社区的总体描述

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

  • 使用 SymPy 的其他主要软件列表

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

  • 开发人员入门信息

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

  • SymPy 新闻

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

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

  • 叙述性页面：对应于不在 Python 源代码中的手动编写的文档页面的 reStructuredText 文件。例如 教程 RST 文件。通常，如果你的文档不是 API 文档，它应该属于叙述性页面。

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

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

Most functions and classes have documentation written inside it in the form of a docstring, which explains the function and includes examples called doctests. The purpose of these docstrings are to explain the API of that class or function. The doctests examples are tested as part of the test suite, so that we know that they always produce the output that they say that they do. Here is an example docstring. Most docstrings are also automatically included in the Sphinx documentation above, so that they appear on the SymPy Documentation website. Here is that same docstring on the SymPy website. The docstrings are formatted in a specific way so that Sphinx can render them correctly for the docs website. The SymPy sources all contain sparse technical documentation in the form of source code comments, although this does not generally constitute anything substantial and is not displayed on the documentation website.

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

SymPy Wiki 可以不经审核由任何人编辑。它包含各种类型的文档，包括：

叙述性文档指南

广泛的文档，或不是围绕API参考的文档，应该作为叙述性文档写在Sphinx文档中（位于`doc/src目录 <https://github.com/sympy/sympy/tree/master/doc/src>`_）。叙述性文档不位于Python源文件中，而是作为独立的reStructuredText文件位于doc/src目录中。SymPy的叙述性文档被定义为集体的文档、教程和指南，这些内容教导用户如何使用SymPy。参考文档应该放在docstrings中，并通过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 文档构建不会失败，而是会在页面上显示为错误。然而，在拉取请求上通过 GitHub Actions 运行的 PDF 构建将会失败。如果在 CI 上 LaTeX PDF 构建失败，可能是因为 LaTeX 数学公式存在问题。

示例

正确:

\int \sin(x)\,dx

不正确:

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

关于如何在 LaTeX 中编写数学公式的更多深入资源，请参阅：

代码

应该逐字打印的文本，例如代码，应该用一对双反引号包围 像这样。

示例

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强调来斜体化，如 *这样*。

示例

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 函数的拼写。

例如，切比雪夫多项式是以帕夫努季·利沃维奇·切比雪夫命名的，他的名字有时从俄语翻译过来时会拼写为“Tchebychev”，但在SymPy中，它应该始终拼写为“Chebyshev”以引用SymPy函数。

示例

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

    """

大写

在所有 SymPy 标题中，首选标题大小写。

示例

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

音调偏好

在 SymPy 文档中，请使用：

  • 现在时态（例如，在接下来的部分，我们将要学习…）

  • 第一人称包容性复数（例如，我们用这种方式做了这件事，但现在我们可以尝试用简短的方式…）

  • 使用泛指代词“你”而不是“一个人”。或者使用“读者”或“用户”。（例如，你可以通过…访问这个功能。用户可以通过…访问这个功能。）

  • 使用性别中立的代词“他们”代替“他”或“她。”（例如，一个好的文档字符串会告诉用户他们需要知道的确切内容。）

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

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

避免使用像“我们只需要再做一件事”这样的多余短语。