使用 Sphinx 在 Latex 文档中制作参考书目答案

【问题标题】：Use Sphinx to make a bibliography in a latex document使用 Sphinx 在 Latex 文档中制作参考书目
【发布时间】：2019-05-16 21:13:05
【问题描述】：

我目前正在使用 Sphinx 生成乳胶文档。我对参考书目有一些问题。我希望参考书目出现在没有章节编号的目录中。

当我将参考书目作为单独的部分包含时，例如使用以下重组文本文件：

************
Bibliography
************

.. bibliography:: NullFeaturesInQGIS.bib
   :style: plain

我最终得到一个名为“参考书目”的编号章节，然后是两页后的实际“参考书目”。

我想要实现的是“参考书目”的目录标题，并且指向参考书目而不需要额外的空白页面。

【问题讨论】：

我假设您使用的是 sphinxcontrib-bibtex 扩展。如果您只是删除 Bibliography 部分标题会发生什么？
如果我删除参考书目部分的标题，我仍然会得到两个空白页面，而且我没有任何目录。
对于一个临时解决方案，我有单独的 index.rst 文件用于来自 Sphinx 的 html 和 Latex 输出。在 html 的 index.rst 文件中，我在 toctree（目录）中包含一个带有参考书目指令的参考书目部分，在乳胶的 index.rst 文件中，我删除了参考书目部分和参考书目指令。这给了我我需要的结果。

标签： latex python-sphinx restructuredtext bibliography

【解决方案1】：

下面显示了两种不同的方法，它们在 Sphinx 的 html 和 latex 输出中创建参考书目部分。

1.使用两个不同的“索引”重组文本文件

在 Sphinx html 和 latex 输出中创建书目部分的一种方法使用两个 index 重组文本文件。

对于 html 输出，index.rst 文件应该是这样的：

===============
Project Heading
===============

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   section_1
   section_2
   section_3
   bibliography

对于 latex 输出，index_latex.rst 文件应如下所示：

===============
Project Heading
===============

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   section_1
   section_2
   section_3

bibliography.rst 文件应该是这样的：

************
Bibliography
************

.. bibliography:: bibtex_filename.bib
   :style: plain

在 Sphinx 配置文件中（例如conf.py），您需要区分两个不同的索引文件。例如：

# The html index document.
master_doc = 'index'

# The latex index document
latex_doc = 'index_latex'

2。使用一个index.rst 文件并使用.. raw:: 指令

以下内容改编自https://github.com/sphinx-doc/sphinx/issues/4775。此方法对 html 和 latex 输出使用相同的 index.rst 文件。 index.rst 文件应该与上面 html 输出中显示的相同，并且应该包含对 bibliography.rst 文件的引用。 bibliography.rst 文件需要以.. raw:: 指令开头：

.. raw:: latex

   \cleardoublepage
   \begingroup
   \renewcommand\chapter[1]{\endgroup}
   \phantomsection

************
Bibliography
************

.. bibliography:: bibtex_filename.bib
   :style: plain

注意

将 Sphinx .. only:: 指令与单个 index.rst 文件一起使用，如下所示不起作用。具体来说，latex 文档将缺少内容。这可能是由于problems with the .. only:: directive.

===============
Project Heading
===============

.. only:: html

   .. toctree::
      :maxdepth: 2
      :caption: Contents:

      section_1
      section_2
      section_3
      bibliography

.. only:: latex

   .. toctree::
      :maxdepth: 2
      :caption: Contents:

      section_1
      section_2
      section_3

【讨论】：

也许这个hack 使用原始乳胶，经过适当调整，可以避免两个分开的 index.rst 文件（未经测试）
感谢 jfbu，它测试了您引用的 hack，它可以正常工作。我现在已将其包含在我的答案中。

【解决方案2】：

在 bibliography.rst 文件中使用 Sphinx .. only:: 指令，如下所示：

.. only:: html

    ************
    Bibliography
    ************

.. bibliography:: bibtex_filename.bib
   :style: plain

并像这样保留一个 index.rst 文件：

===============
Project Heading
===============

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   section_1
   section_2
   section_3
   bibliography

帮我解决了。

【讨论】：