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

Question

我使用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的屏幕截图：

大肆宣传还是什么？

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问题处理同样的问题（它来自2011年）：

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

引用：

  

你的index.rst没有标题，对吗？基本上狮身人面像狼吞虎咽   最高级别的标题（然后由文档替换）   frontmatter）。

这个问题在2011年被“搁置”，可能不会被认为是失败的行为。然后它刚刚在GitHub上关闭而没有被“修复”。因此，正如格奥尔格在那张票中写的那样，Sphinx确实只消耗了最高等级，而其内容并没有出现在任何地方。

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

Answer 2

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

$ make latexpdf

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

OPs原始命令是

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

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