5

I use sphynx to generate documentation from static .rst files (no docstrings extraction).

I have two files in my repository:

index.rst

.. toctree::

   intro

and intro.rst

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

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

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

Below is screenshot of pdf obtained by running sphinx-build -b latex . _build; cd _build; pdflatex * :

enter image description here

Flabbergasting or what?

4

2 回答 2

5

感谢您提供工作示例。我可以在 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 没有标题，对吧？基本上，Sphinx 吞噬了最顶层的标题（然后被文档 frontmatter 替换）。

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

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

于 2015-01-21T22:38:07.647 回答
1

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

$ make latexpdf

我看到了Will be skippedPDF 输出中的标题。

预期的 PDF 输出

OPs 的原始命令是

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

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

于 2015-01-23T15:06:16.117 回答