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

Question

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

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

索引.rst

.. toctree::

   intro

和介绍

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

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

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

以下是通过运行获得的pdf截图sphinx-build -b latex . _build; cd _build; pdflatex *：

大惊小怪还是什么？

Answer 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 issue 处理了同样的问题（它是从 2011 年开始的）：

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

引用：

你的 index.rst 没有标题，对吧？基本上，Sphinx 吞噬了最顶级的标题（然后由文档的frontmatter 替换）。

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

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