3

我正在使用托管在https://readthedocs.org上的 sphinx 来生成 HTML 和 PDF 格式的文档。HTML 工作正常。PDF 也成功构建，但存在嵌套问题：我希望从我的目录链接的每个顶级.rst文档都作为顶级“章节”包含在 PDF 中。但是，它们实际上是作为子部分包含的，从属于首页index.rst内容。这是我的index.rst：

====
Blah
====

Welcome to the Blah project. It does various things.


Quickstart
==========

To download and install the Python package:
-------------------------------------------

* `python -m pip install Blah`


To run the demo:
----------------

* `python -m Blah --demo`


.. NEED SOME DIRECTIVE HERE
   to tell sphinx/latex that Installation, BasicUsage
   and friends are NOT subsections of "To run the demo"
   but rather chapters at the same level as "Quickstart".


.. toctree::
   :caption: Table of Contents
   :maxdepth: 2

   Installation
   BasicUsage
   AdvancedUsage
   License


Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

...这个屏幕截图显示了我在 PDF 中得到的内容：

显示过度嵌套嵌套的 pdf 屏幕截图

...而我希望“如何安装 Blah”成为第 2 章，“基本用法”成为第 3 章，依此类推。（HTML 看起来井井有条：登录页面分为三个部分标题，称为Quickstart，然后是 Table of Contents，然后是Indices 和 Tables。）

在制作 PDF 的情况下，我的 search-foo 未能找到任何告诉 sphinx 的方法，“在此处上升两级”或“在此处结束当前章节”（请参阅index.rst​​清单中的评论“此处需要一些指示”以上）。这实际上可能吗？

章节文件之一的内容Installation.rst如下：

How to Install Blah
===================

It's on pypi.org so just use `pip`.

其他文件 ,BasicUsage.rst和AdvancedUsage.rst可以License.rst出于示例的目的从 toc 中删除，或者以相同的方式构建：带有 -=下划线标题的单行（与上面的“快速入门”相同的下划线级别）。

4

2 回答 2

2

正如 jez 所建议的，如果您将其作为 index.rst 中的第一件事，在其他标题之前包含它，则可以将 toc children 作为章节：

================
 Document title
================

.. toctree::
   :hidden:

   installation
   gettingstarted
   usage
   api_reference
   explanations



Hello
-----
special stuff that will show first in the html docs..

Second heading
--------------
mor text

我将其设置:hidden:为仅将其作为侧边菜单和/或 PDF 版本的结构强制执行。然后，您可以在页面的其余部分使用您想要的任何标记，以便它在 html 文档上看起来不错（例如，我见过的两列和三列技巧）。这种自定义格式（你好和第二个标题）最终将作为文档末尾的额外章节......不是最好的......但仍然可用：嘿顺便说一句，一旦你阅读了整本书，这里是最好的部分的链接；）

真的，所有这些都是黑客，真正的解决方案是 PDF 的单独索引是史蒂夫提到的更好的方法，可能有一些includes 以避免重复。

于 2020-04-20T22:29:49.557 回答
0

一个答案，或者更确切地说是解决方法，似乎是在目录之前完全避免使用任何标题（顶级主标题“Blah”除外）。然后目录条目被包含为章节。在乳胶版本中，“快速入门”可以变成自己的章节，包含在 toc 中。（为了使 html 版本和 latex 版本相互分歧，正如@StevePiercy 在评论中所建议的那样，在latex_documents参数中为 Latex 模式配置不同的索引文件conf.py。）

于 2020-03-28T19:13:30.457 回答