Python Sphinx 在生成 pdf 时跳过第一部分答案

【问题标题】：Python Sphinx skips first section when generating pdfPython Sphinx 在生成 pdf 时跳过第一部分
【发布时间】：2015-01-15 14:04:59
【问题描述】：

我使用 sphynx 从静态 .rst 文件生成文档（不提取文档字符串）。

我的存储库中有两个文件：

index.rst

.. toctree::

   intro

和intro.rst

Will be skipped
===============

Where is my parent section?
---------------------------

Second section
==============

下面是运行sphinx-build -b latex . _build; cd _build; pdflatex *得到的pdf截图：

大吃一惊还是什么？

【问题讨论】：

标签： python latex python-sphinx pdflatex toctree

【解决方案1】：

感谢您提供工作示例。我可以在 Windows 上使用 Sphinx 1.2.3 重现您的观察结果。据我所见，HTML 输出按预期工作。使用 LaTeX 构建器，生成以下文档结构：

\chapter{Where is my parent section?}
\label{intro:will-be-skipped}\label{intro::doc}\label{intro:where-is-my-parent-section}

\chapter{Second section}
\label{intro:second-section}

我发现您的文档没有定义标题令人怀疑。作为一种解决方法，我发现添加更高的层次结构是可行的，而将其放入 index.rst 或 intro.rest 并不重要。这是修改后的 index.rst：

=====
TITLE
=====

.. toctree::

   intro

导致：

然后我进一步寻找了这个问题，发现这个 Bitbucket/GitHub 问题处理了同样的问题（它是从 2011 年开始的）：

https://bitbucket.org/birkenfeld/sphinx/issue/632/section-versus-chapter-oddity-in-latex https://github.com/sphinx-doc/sphinx/issues/632

引用：

你的 index.rst 没有标题，对吧？基本上狮身人面像狼吞虎咽最顶层的标题（然后被文档替换前题）。

该问题在 2011 年被“搁置”，可能不被认为是失败的行为。然后它最近才在 GitHub 上关闭而没有被“修复”。因此，正如 Georg 在那张票中所写，Sphinx 确实只是消耗了最高层级，而它的内容却没有出现在任何地方。

因此：添加“标题层次结构”，无论您如何命名，都是正确的解决方案。

【讨论】：

只是为了澄清，缺少的标题在index.rst

【解决方案2】：

使用 Ubuntu 14.04 和 texlive 如果我使用 sphinx-quickstart（单独的源目录和构建目录）创建新的 Sphinx 项目，请将示例文件放入 source 目录并使用以下方式构建：

$ make latexpdf

我在 PDF 输出中看到了 Will be skipped 标题。

OP 的原始命令是

$ sphinx-build -b latex . _build; cd _build; pdflatex *

构建文档，这与使用latex all-pdf 的Makefile 中的latexpdf 目标略有不同。但是，如果我使用与 sphinx-quickstart 创建的 conf.py 相同的新项目目录，我仍然会使用 OPs 命令序列在 PDF 中看到 Will be skipped 输出。我会查看您正在使用的 conf.py 设置，这些设置可能会为解决方案提供线索。

【讨论】：