用法

配置

参考文献文件和编码

Added in version 2.0.0.

要配置插件，请在您的 conf.py 文件中，将 bibtex_bibfiles 设置为您的参考文献文件列表。例如，最小的配置可能如下所示：

extensions = ['sphinxcontrib.bibtex']
bibtex_bibfiles = ['refs.bib']

在参考文献文件中，LaTeX 控制字符会自动转换为 Unicode 字符（例如，将 \'e 转换为 é ）。请确保在需要格式化百分号时写入 \%。

您可以在 conf.py 文件中设置参考文献文件的编码，使用 bibtex_encoding 变量。如果没有指定编码，则假定为 utf-8-sig。例如：

bibtex_encoding = 'latin'

Bibliography 风格

您可以通过在 conf.py 文件中设置 bibtex_default_style 变量来更改参考文献的样式。如果未指定，则使用 alpha 样式。其他受支持的样式是 plain、unsrt 和 unsrtalpha。例如：

bibtex_default_style = 'unsrt'

您还可以创建自己的样式（请参阅 自定义格式化，排序和标记）。

引用样式

Added in version 2.2.0.

你可以通过在 conf.py 文件中设置 bibtex_reference_style 变量来更改内联引用样式（即引用标记本身的格式）。目前可用的内置样式有：

• label ：使用参考文献样式生成的标签。与 biblatex 的 numeric 和 alphabetic 样式类似（取决于参考文献样式的标签样式）。这是默认样式。

• author_year ：使用作者和年份。与 natbib 和 biblatex 的 authoryear 样式类似。请注意，这不会从参考文献中删除标签。这是因为，在 docutils 中，每个引用都必须有标签。

• super ：使用由参考文献样式生成的标签作为上标。这种样式最适合与数字型参考文献样式（如 plain ）配合使用。类似于 natbib 的 super 样式和 biblatex 的 \supercite 命令。

内联参考文献样式可以通过在 conf.py 文件中设置 bibtex_foot_reference_style 变量来配置。目前可用的内置样式有：

• foot ：使用脚注作为括号内的引用，使用作者和脚注作为文本引用。这是默认样式（也是唯一的内置样式）。

Python 包可以通过 sphinxcontrib.bibtex.style.referencing entry point 使用的入口点组。请参阅 sphinxcontrib-bibtex 的 pyproject.toml 配置文件，

工具提示

Added in version 2.4.2.

扩展将生成纯文本工具提示，用于通过 html title 属性预览引用，允许在悬停时预览引用。

禁用这些工具提示的方法是将 bibtex_tooltips 设置为 False。

默认情况下，将使用参考文献样式来格式化工具提示。您可以设置 bibtex_tooltips_style 选项来使用不同的样式。

角色和指令

:cite:p:

Added in version 2.2.0.

创建括号内的引用，指向参考文献条目。这将在括号内放置引用信息（作者和年份或标签，取决于样式）。类似于 natbib 的 \citep 命令，或者 biblatex 的 \parencite 命令。例如：

We will make use of non-standard analysis :cite:p:`1987:nelson`.

等价于以下 LaTeX 代码：

We will make use of non-standard analysis \citep{1987:nelson}.

多个键可以一次性指定：

I love analysis :cite:p:`1987:nelson,2001:schechter`!

:cite:t:

Added in version 2.2.0.

创建文本引用。这通常会呈现第一个作者的名称，后跟年份或标签，具体取决于引用样式。类似 natbib 的 \citet 命令，或者 biblatex 的 \textcite 命令。例如：

See :cite:t:`1987:nelson` for an introduction to non-standard analysis.

等价于以下 LaTeX 代码：

See \citet{1987:nelson} for an introduction to non-standard analysis.

这里也可以一次指定多个键。

:cite:ps:

:cite:ts:

:cite:ct:

:cite:cts:

Added in version 2.2.0.

这些角色修改了 cite:p 和 cite:t。以 c 开头的角色会将第一个字母大写。以 s 结尾的角色会给出完整的作者列表。

:cite:alp:

:cite:alps:

Added in version 2.6.0.

这些角色与 cite:p 和 cite:ps 相同，但会抑制括号。这对于需要在引用前或引用后添加格式化的预文本或后文本很有用。

参见

添加预文本和后文本到引用

:cite:

这是 cite:p 角色的别名，用于创建括号内的引用。提供此别名是为了方便和与旧版本兼容。

:cite:label:

:cite:labelpar:

Added in version 2.2.0.

使用标签创建引用。使用 par 版本来包含括号。

:cite:year:

:cite:yearpar:

Added in version 2.2.0.

使用年份创建引用。使用 par 版本来包含括号。

:cite:author:

:cite:authors:

:cite:authorpar:

:cite:authorpars:

:cite:cauthor:

:cite:cauthors:

Added in version 2.2.0.

使用作者创建引用。使用 par 版本来包含括号，使用 c 版本来将第一个字母大写。

:cite:empty:

Added in version 2.3.0.

注册引用键，使其被引用但不生成引用，类似于 LaTeX 的 nocite 命令。

.. bibliography::

创建所有引用的文献。在 Sphinx 中，引用在整个项目中是全局解析的。通常，您的整个项目中只有一个文献指令，它收集所有引用。引用键也可以显式列出，参见 列出引用键。

警告

Sphinx 将尝试在所有文档中解析对文献的引用，因此您必须小心，确保没有引用键被重复包含。

以下选项是可识别的（所有都是可选的）。

:all:

包含所有引用，而不仅仅是被引用的引用（相当于 LaTeX 中的 \nocite{*} ）。例如：

.. bibliography::
   :all:

:notcited:

导致未被引用的引用被包含。列出的引用仍然被包含。

:cited:

这是默认值，不需要指定。

:style:

覆盖默认的文献样式。例如：

.. bibliography::
   :style: unsrt

:list:

:enumtype:

:start:

阅读 点列表和枚举列表。

:labelprefix:

See 标签前缀.

:keyprefix:

See 键前缀.

:filter:

阅读 过滤器。请注意，列出的引用始终被包含，无论是否进行过滤。

:footcite:p:

Added in version 2.3.0.

创建括号内的脚注引用，指向参考文献条目。例如：

We will make use of non-standard analysis\ :footcite:p:`1987:nelson`.

等价于以下 LaTeX 代码：

We will make use of non-standard analysis\footcite{1987:nelson}.

注意在引用之前使用 反斜杠转义的空格 ，来抑制原本会在脚注前出现的空格。

与所有引用角色一样，可以指定多个键：

I love analysis\ :footcite:p:`1987:nelson,2001:schechter`!

:footcite:t:

Added in version 2.3.0.

创建文本脚注引用，指向参考文献条目。例如：

See :footcite:t:`1987:nelson` for an introduction to non-standard analysis.

等价于以下 LaTeX 代码：

See Nelson\footcite{1987:nelson} for an introduction to non-standard analysis.

这里也可以一次指定多个键。

:footcite:ps:

:footcite:ts:

:footcite:ct:

:footcite:cts:

Added in version 2.3.0.

这些角色修改了 footcite:p 和 footcite:t。以 c 开头的角色会将第一个字母大写。以 s 结尾的角色会给出完整的作者列表。

:footcite:

Added in version 2.0.0.

这是 footcite:p 角色的别名，用于创建括号内的脚注引用。提供此别名是为了方便和与旧版本兼容。

.. footbibliography::

Added in version 2.0.0.

在当前文档中被引用的所有引用的脚注将在此位置创建。通常，每个文档的底部都有一个脚注文献指令，其中包含脚注引用。

标准数字脚注标签被使用，因此标签样式被忽略。脚注按文档中出现的顺序插入，因此排序样式也被忽略。

如果在同一文档中多次指定，脚注只会为文档中之前尚未有脚注的引用创建。

使用 MyST 语法的 Markdown

如果您使用 MyST 解析器，所有角色和指令也可以在 Markdown 语法中使用。例如：

See {cite:p}`1987:nelson` for an introduction to non-standard analysis.

```{bibliography} references.bib
```

参见

https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html

高级功能

添加预文本和后文本到引用

Added in version 2.6.0.

您可以使用以下语法向任何引用添加未格式化的预文本和后文本：

The axioms were introduced by :cite:t:`{see}1977:nelson`.
The axioms were introduced by :cite:t:`1977:nelson{p. 1166}`.
The axioms were introduced by :cite:t:`{see}1977:nelson{p. 1166}`.
Axioms were introduced :cite:p:`{see}1977:nelson`.
Axioms were introduced :cite:p:`1977:nelson{p. 1166}`.
Axioms were introduced :cite:p:`{see}1977:nelson{p. 1166}`.

对脚注引用不支持预文本和后文本。

对括号内的引用，您可以使用 cite:alp 和 cite:alps 角色。这些角色会抑制括号，让您在正确的格式和位置添加它们：

The three new axioms [the *IST axioms*, :cite:alp:`1977:nelson`] are discussed next.

按 Bib 文件拆分文献

Added in version 2.0.0.

如果您希望每个文献只包含来自特定 bib 文件的引用，您可以将相关的 bib 文件作为指令的可选参数指定。

以下示例显示了如何将您的引用按文章和书籍拆分，假设您的文章位于 articles.bib 中，您的书籍位于 books1.bib 和 books2.bib 中。

.. rubric:: Articles

.. bibliography:: articles.bib

.. rubric:: Books

.. bibliography:: books1.bib books2.bib

该 bib 文件必须是相对于包含文档的路径。

点列表和枚举列表

Added in version 0.2.4.

您可以更改用于呈现文献的列表类型。默认情况下，将生成一个标准引用的段落。但是，您也可以生成点列表或枚举列表。

.. bibliography::
   :list: bullet
   :all:

.. bibliography::
   :list: enumerated
   :all:

请注意，对这些类型的文献列表的引用不会被解析。

对于枚举列表，您还可以指定类型（默认为 arabic ）和序列的开始（默认为 1 ）。

.. bibliography::
   :list: enumerated
   :enumtype: upperroman
   :start: 3
   :all:

enumtype 可以是 arabic (1, 2, 3,...)、 loweralpha (a, b, c,...)、 upperalpha (A, B, C,...)、 lowerroman (i, ii, iii,...) 或 upperroman (I, II, III,...)。

start 可以是任何正整数 (1, 2, 3,...) 或 continue ，如果您希望枚举从最后一个 bibliography 指令继续。这在您将文献拆分为多个部分但仍然希望连续枚举条目时非常有用。

列出引用键

Added in version 2.3.0.

如果您有很多未引用的引用，那么使用 cite:empty 可能更方便。您可以直接在希望它们出现的文献部分下列出引用键。每个引用键可以单独占一行。如果使用了键前缀选项（参见 键前缀），则这些键不应包含前缀。例如：

.. bibliography::

   nelson1987
   boole1854

这将导致文献生成对所有被引用的引用的引用，以及对 bibtex 键 nelson1987 和 boole1854 的引用。无论过滤如何，列出的键始终被包含。因此，如果您只想包含列出的键，您可以使用 :filter: False 选项：

.. bibliography::
   :filter: False

   nelson1987
   boole1854

请参阅 过滤器 以获取有关过滤的更多信息。

标签前缀

Added in version 0.2.5.

如果你有多个参考文献列表，并且遇到重复的标签问题，可以使用 labelprefix 选项。

.. rubric:: References

.. bibliography::
   :cited:
   :labelprefix: A

.. rubric:: Further reading

.. bibliography::
   :notcited:
   :labelprefix: B

键前缀

Added in version 0.3.3.

如果你有多个参考文献列表，并且你希望在不同的文档中重复条目，那么可以使用 keyprefix 选项。

例如，假设您有两个文档，并且希望在这两个文档中都引用 boole1854 ，那么文献条目将显示在两个文档中。在一个文档中，您可以这样写：

See :cite:`a-boole1854`

.. bibliography::
   :labelprefix: A
   :keyprefix: a-

而在另一个文档中，你可以使用：

See :cite:`b-boole1854`

.. bibliography::
   :labelprefix: B
   :keyprefix: b-

文献列表将生成两个 boole1854 的条目，链接和反向链接如预期的那样。

如果您列出了引用键，那么应该包括那些 没有 键前缀。例如：

.. bibliography::
   :labelprefix: B
   :keyprefix: b-

   nelson1987

参见

本地文献

过滤器

Added in version 0.2.7.

虽然 cited、 all 和 notcited 选项以及 列出引用键 可以覆盖许多用例，但有时需要更高级的文献条目选择。为此，您可以使用 filter 选项：

.. bibliography::
   :list: bullet
   :filter: author % "Einstein"

在 filter 选项中指定的字符串必须是有效的 Python 表达式。

备注

使用 ast.parse() 解析表达式，然后使用 ast.NodeVisitor 进行评估。

过滤器表达式支持：

• 布尔运算符 and, or。

• 一元运算符 not。

• 比较运算符 ==, <=, <, >=, 和 >。

• 使用 % 运算符进行正则表达式匹配，其中左侧是要匹配的字符串，右侧是正则表达式。匹配不区分大小写。例如：

  .. bibliography::
     :list: bullet
     :filter: title % "relativity"
  

  将包括标题中包含单词 "relativity" 的所有条目。

  备注

  实现使用 re.search()。

• 单引号和双引号字符串，例如 'hello' 或 "world"。

• 集合字面量，例如 {"hello", "world"}，以及集合运算符 &，|，in 和 not in。

  Added in version 0.3.0.

• 各种标识符，例如：

  • type 是条目类型，作为小写字符串（例如 "inproceedings"）。

  • key 是条目键，作为小写字符串（因为键被认为是不区分大小写的）。

  • cited 在条目被引用时评估为 True，否则为 False。

  • docname 评估为当前文档的名称。

    Added in version 0.3.0.

  • docnames 评估为条目被引用的文档名称集合。

    Added in version 0.3.0.

  • True 和 False。

  • author 是标准格式的作者字符串（姓，名），用 "and" 分隔。

  • editor 类似于 author，但用于编辑人员。

  • 任何其他（小写）标识符评估为包含相应字段值的字符串，例如 title，publisher，year 等等。如果条目中缺少该项，则它会评估为空字符串。以下是如何编写表达式来过滤可选字段的示例：

    .. bibliography::
       :list: bullet
       :filter: cited and year and (year <= "2003")
    

    这将包括所有被引用的条目，这些条目的年份小于或等于 2003；任何未指定年份的条目将被省略。

本地文献

最简单的方法是在每个文档中使用 footcite 和 footbibliography。

如果您更喜欢使用常规引用而不是脚注，那么可以使用 keyprefix 和 filter 选项来实现 cite 和 bibliography 的本地文献。

本地文献的 filter 系统只能在多个文档中使用相同的引用键时使用。这通常不是这样的。如果您需要在多个文档中引用多个本地文献的相同引用，那么可以使用 keyprefix 系统；请参阅 键前缀。

要创建仅包含当前文档中引用过的文献的参考文献列表，请使用以下过滤器：

.. bibliography::
   :filter: docname in docnames

更一般地，您可以为仅从特定文档引用的文献创建参考文献列表：

.. bibliography::
   :filter: {"doc1", "doc2"} & docnames

此参考文献列表将包含所有从 :file:`doc1.rst 或 :file:`doc2.rst 中引用的文献。另一个假设的例子：

.. bibliography::
   :filter: cited and ({"doc1", "doc2"} >= docnames)

此参考文献列表将包含所有在 :file:`doc1.rst 或 :file:`doc2.rst 中引用的文献，但其他地方没有引用。

自定义格式化，排序和标记

pybtex 提供了一种非常强大的方式来创建和注册新样式，使用 setuptools 入口点，在此处进行了文档说明：https://docs.pybtex.org/api/plugins.html

简化地将以下代码添加到您的 conf.py:

import pybtex.plugin
from pybtex.style.formatting.unsrt import Style as UnsrtStyle
from pybtex.style.template import toplevel # ... and anything else needed

class MyStyle(UnsrtStyle):
    def format_XXX(self, e):
        template = toplevel [
            # etc.
        ]
        return template.format_data(e)

pybtex.plugin.register_plugin('pybtex.style.formatting', 'mystyle', MyStyle)

现在 mystyle 将作为格式化样式可用：

bibtex_default_style = 'mystyle'

简单的示例可在此处找到：https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-bibliography_style_nowebref

格式化代码使用了一个非常直观的模板引擎。unsrt 的源代码提供了许多优秀的示例：https://bitbucket.org/pybtex-devs/pybtex/src/master/pybtex/style/formatting/unsrt.py?at=master&fileviewer=file-view-default

上面的示例仅演示了自定义格式化样式插件。同样，可以注册自定义作者/编辑命名插件（使用 pybtex.style.names 组），标记插件（使用 pybtex.style.labels 组）和排序插件（使用 pybtex.style.sorting 组）。一些最小化的示例展示了如何创建自定义标签样式，这些示例可在此处找到：

• https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-bibliography_style_label_1

• https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-bibliography_style_label_2

自定义内联引用

Added in version 2.2.0.

创建并注册您自己的引用样式。例如，希望使用作者-年份样式，而不是默认的方括号。只需将以下代码添加到您的 conf.py 中：

from dataclasses import dataclass, field
import sphinxcontrib.bibtex.plugin

from sphinxcontrib.bibtex.style.referencing import BracketStyle
from sphinxcontrib.bibtex.style.referencing.author_year \
    import AuthorYearReferenceStyle


def bracket_style() -> BracketStyle:
    return BracketStyle(
        left='(',
        right=')',
    )


@dataclass
class MyReferenceStyle(AuthorYearReferenceStyle):
    bracket_parenthetical: BracketStyle = field(default_factory=bracket_style)
    bracket_textual: BracketStyle = field(default_factory=bracket_style)
    bracket_author: BracketStyle = field(default_factory=bracket_style)
    bracket_label: BracketStyle = field(default_factory=bracket_style)
    bracket_year: BracketStyle = field(default_factory=bracket_style)


sphinxcontrib.bibtex.plugin.register_plugin(
    'sphinxcontrib.bibtex.style.referencing',
    'author_year_round', MyReferenceStyle)

警告

您必须将您的样式装饰为数据类，并为每个字段 包含类型注解，以确保在 sphinxcontrib-bibtex 实例化您的样式时正确传递这些值。

现在 author_year_round 将作为格式化样式可用：

bibtex_reference_style = 'author_year_round'

最简示例可在此处查看：https://github.com/mcmtroffaes/sphinxcontrib-bibtex/tree/develop/test/roots/test-citation_style_round_brackets

自定义 HTML 锚点

Added in version 2.4.0.

对于每个引用和每个参考文献，都会生成一个形式为 idxxx``（其中 ``xxx 是某个数字）的标识符。这些标识符可以用作 HTML 锚点。它们由 docutils 自动生成，因此保证不会发生冲突。

然而，有时从其他未使用 Sphinx 生成的外部文档中引用参考文献条目会很有用。由于更新文档时生成的标识符很容易出错，您可以通过字符串模板自定义它们，如果需要的话。如果您这样做，确保没有锚点会冲突的责任在于您，通过在您的 conf.py 文件中设置适当的标识符模板来实现这一点，例如如下所示：

bibtex_cite_id = "cite-{bibliography_count}-{key}"
bibtex_footcite_id = "footcite-{key}"
bibtex_bibliography_id = "bibliography-{bibliography_count}"
bibtex_footbibliography_id = "footbibliography-{footbibliography_count}"

如果每个文档最多只有一个 bibliography 指令，那么您也可以使用：

bibtex_cite_id = "cite-{key}"

bibliography_count 模板变量计算当前文档中的 bibliography 指令数量，从而为每个文档内的 bibliography 指令提供一个唯一的编号。footbibliography_count 模板变量的工作原理类似，但适用于 footbibliography 指令。key 模板变量对应于 bibtex 引用键，包括指定的键前缀（如果有的话）。格式化模板后，结果字符串将通过 docutils 的 make_id 函数进行过滤，该函数会移除并/或翻译任何非法字符。特别是冒号和下划线将被转换为破折号。

警告

如果在任何文档中有多个 bibliography 指令，那么你*必须*将 bibliography_count 包含在 bibtex_cite_id 模板中，以避免重复标识符的问题，即使没有重复引用也是如此。这是因为在插件确定是否需要包含引用之前，必须为每个 bibliography 指令的每个键生成一个标识符。

自定义参考文献标题

Added in version 2.0.0.

默认情况下，bibliography 和 footbibliography 指令仅插入一个段落。可以通过设置 bibtex_bibliography_header 和 bibtex_footbibliography_header 配置变量来为其添加标题。例如，在您的 conf.py 中可以这样设置：

bibtex_bibliography_header = ".. rubric:: References"
bibtex_footbibliography_header = bibtex_bibliography_header

这会向每个参考文献添加一个标题。

抑制警告

Added in version 2.3.1.

抑制来自 sphinxcontrib-bibtex 的所有警告（这可能不是一个好主意！），在您的 conf.py 中添加如下内容：

suppress_warnings = ["bibtex"]

要抑制子集警告（例如重复标签警告），您可以使用：

suppress_warnings = ["bibtex.duplicate_label"]

完整的警告子类型列表：

bibtex.bibfile_data_error
bibtex.bibfile_error
bibtex.duplicate_citation
bibtex.duplicate_id
bibtex.duplicate_label
bibtex.filter_overrides
bibtex.filter_syntax_error
bibtex.key_not_found
bibtex.list_type_error
bibtex.missing_field

已知问题和解决方法

LaTeX 格式在 Bibtex 条目内

除了简单的 unicode/LaTeX 符号转换，pybtex 不支持在 bib 文件中使用 LaTeX 格式。由于 sphinxcontrib-bibtex 使用 pybtex 解析和格式化 bibtex 条目，因此该限制也传递给了 sphinxcontrib-bibtex。

编码：百分号

确保在您的 bib 文件中始终使用 \% 表示百分号（除非文件包含真正的注释），否则 pybtex 解析器将忽略该行其余部分。

使用 :style: plain 时的重复标签

使用 :style: plain 时，标签是数字，每个 bibliography 指令从 [1] 重新开始。因此，当插入多个 :style: plain 的 bibliography 指令时，您将不可避免地得到重复的条目标签。有几种方法可以解决这个问题：

• 使用单个 bibliography 指令来包含所有引用。

• 使用 labelprefix 选项，如上文所述。

• 使用具有非数字标签的样式，例如 :style: alpha。

LaTeX 后端在图形标题中处理引用时失败。

Sphinx 为引用生成 \phantomsection 命令，然而 LaTeX 不支持在图形标题中处理这些命令。您可以通过在您的 conf.py 中添加以下代码来解决这个问题：

latex_elements = {
 'preamble': r'''
     % make phantomsection empty inside figures
     \usepackage{etoolbox}
     \AtBeginEnvironment{figure}{\renewcommand{\phantomsection}{}}
 '''
}

警告

上述解决方法不再有效。如果您知道解决方案，请在 https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/276 报告。

HTML/文本输出和 LaTeX 后端之间的不匹配。

Sphinx 的 LaTeX 编写器目前会将所有引用收集在一起，并将它们放在单独的页面上，每个页面上有一个单独的标题，而 HTML 和文本编写器将引用放在它们定义的位置。如果您在 Sphinx 中使用常规引用，这也会发生在 sphinxcontrib-bibtex 本身：它与 sphinxcontrib-bibtex 无关。

要在两个输出之间获得更接近的匹配，请告诉 Sphinx 抑制其自定义参考文献转换，在您的 conf.py 中添加以下代码：

import sphinx.builders.latex.transforms

class DummyTransform(sphinx.builders.latex.transforms.BibliographyTransform):
    def run(self, **kwargs):
        pass

sphinx.builders.latex.transforms.BibliographyTransform = DummyTransform

然后创建 references.rst 文件，并将其包含在您的 toctree 末尾，内容如下：

References
==========

.. raw:: latex

    \begingroup
    \def\section#1#2{}
    \def\chapter#1#2{}
    \begin{thebibliography}{1234}

.. bibliography::

.. raw:: latex

    \end{thebibliography}
    \endgroup

参见

此问题正在Sphinx的bug跟踪器上进行追踪，您可以在以下链接中找到相关信息。如果上述解决方案不适用于您的情况，您或许还能在那里发现其他变通方法：https://github.com/sphinx-doc/sphinx/issues/4775

在 toctree 指令中，引用未被渲染。

当文档标题中包含引用时，toctree 指令将简单地将引用的目标用于渲染目录，而不是完全渲染的引用。

这似乎是 toctree 指令的限制。目前还没有已知的解决方法。

使用 Numpydoc 时，在脚注引用中使用未知的目标名称。

Numpydoc 有时会重复一些 Python 对象（例如成员函数）的简短描述（即 docstring 的第一行）。如果发生这种情况，解决方法是不在 docstring 的第一行中包含脚注引用。相反，请将它们放在长描述中。或者，在您的 conf.py 文件中设置 numpydoc_class_members_toctree 为 False。这将导致 numpydoc 不重复类成员的简短描述。

当运行 pytest 时出现导入错误

测试套件依赖于安装的入口点，因此 sphinxcontrib-bibtex 在没有首先安装包的情况下无法进行测试。要运行测试，请按照以下步骤操作（最好在虚拟环境中）：

pip install -e .
cd test/
pytest