Python Sphinx 在生成 pdf 时跳过第一部分
Python Sphinx skips first section when generating pdf
我使用 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截图：
目瞪口呆还是什么？
感谢您提供工作示例。我可以在 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
引用：
Your index.rst doesn't have a title, right? Basically Sphinx gobbles
up the most toplevel title (which is then replaced by the document
frontmatter).
那个问题是 "on hold" 早在 2011 年就提出的，可能它不被认为是失败的行为。然后它最近才在 GitHub 上关闭而不是 "fixed"。因此，正如 Georg 在那张票中所写的那样，Sphinx 确实只消耗了最高层级，而其内容不会出现在任何地方。
因此：加上一个"title hierarchy"，不管怎么命名，都是妥妥的解决办法。
使用 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 设置，这些可能会为解决方案提供线索。
我使用 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截图：
目瞪口呆还是什么？
感谢您提供工作示例。我可以在 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
引用：
Your index.rst doesn't have a title, right? Basically Sphinx gobbles up the most toplevel title (which is then replaced by the document frontmatter).
那个问题是 "on hold" 早在 2011 年就提出的，可能它不被认为是失败的行为。然后它最近才在 GitHub 上关闭而不是 "fixed"。因此，正如 Georg 在那张票中所写的那样，Sphinx 确实只消耗了最高层级，而其内容不会出现在任何地方。
因此：加上一个"title hierarchy"，不管怎么命名，都是妥妥的解决办法。
使用 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 设置，这些可能会为解决方案提供线索。