快速上手

概述

bibtex 插件允许通过 bibliography 指令以及 :cite:p: 和 :cite:t: 角色，将 BibTeX 引用插入到由 Sphinx 生成的文档中。这些功能与 LaTeX 中的 thebibliography 环境以及 \citet 和 \citep 命令类似。

对于格式化，该插件依赖于由 Andrey Golovizin 编写的 pybtex。该插件受到 Matthew Brett 的 bibstuff.sphinxext.bibref 以及 Weston Nielson 的 sphinx-natbib 启发。

• 下载：https://pypi.org/project/sphinxcontrib-bibtex/#files

• 文档：https://sphinxcontrib-bibtex.readthedocs.io/en/latest/

• 开发：https://github.com/mcmtroffaes/sphinxcontrib-bibtex/

安装

通过运行 pip install sphinxcontrib-bibtex 安装该模块，或者使用 pip install -e . 从源代码安装。然后添加：

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

在您的 Sphinx 配置文件 conf.py 中添加：

最小示例

在您的项目文档中，您可以使用 :cite:t: 引用文本引用，使用 :cite:p: 引用脚注引用，并使用 .. bibliography:: 插入参考文献。示例 ：

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

.. bibliography::

其中， refs.bib 文件应包含条目:

@Book{1987:nelson,
  author = {Edward Nelson},
  title = {Radically Elementary Probability Theory},
  publisher = {Princeton University Press},
  year = {1987}
}

默认风格下，这将呈现为：

See Nelson [Nel87a] for an introduction to non-standard analysis. Non-standard analysis is fun [Nel87a].

[Nel87a] (1,2)

Edward Nelson. Radically Elementary Probability Theory. Princeton University Press, 1987.

在 Sphinx 中，引用是在所有文档中全局解析的。通常情况下，您会在整个项目中使用单一的 bibliography 指令来收集所有引用。虽然也支持在项目中使用多个 bibliography 指令的高级用例，但您需要注意避免重复引用。

与 Sphinx 不同，脚注是每篇文档本地解析的。要实现每篇文档本地的参考文献列表，您可以使用如下方式表示引用：

See :footcite:t:`1987:nelson` for an introduction to non-standard analysis.
Non-standard analysis is fun\ :footcite:p:`1987:nelson`.

.. footbibliography::

这将呈现为：

See Nelson[1] for an introduction to non-standard analysis. Non-standard analysis is fun[1].

[1] (1,2)

Edward Nelson. Radically Elementary Probability Theory. Princeton University Press, 1987.

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

通常情况下，您会在每个文档的底部使用单一的 footbibliography 指令来表示脚注引用。尽管支持在每个文档中使用多个 footbibliography 指令的高级用例，但由于所有内容都是 local，因此在使用脚注时不会出现重复引用的问题。