结合内联部分管理 Sphinx toctrees [英] Managing Sphinx toctrees combined with inline sections

问题描述

我正在尝试学习如何管理与其他内容位于同一文件中的 toctree 元素.

I'm trying to learn how I can manage a toctree element that is located in the same file as other content.

假设我有一个看起来像这样的 thingamajig.rst 章节:

Suppose I have a thingamajig.rst chapter that looks like this:

Thingamajigs
============

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun

当我渲染它时 --- foo/bar/baz 有它们自己的 .rst 文件 --- 它看起来像这样:

When I render it --- foo/bar/baz have their own .rst files --- it looks like this:

但是如果我在目录树之前移动 Overview 部分，那么它会将目录树向下推入概述部分:

But if I move the Overview section before the toctree, then it pushes the toctree down into the Overview section:

Thingamajigs
============

Overview
++++++++

Thingamajigs are fun

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

有什么方法可以让我的目录树在概览部分之后，但位于 Thingamajigs 部分下?

Is there any way to have my toctree after the Overview section, but located under the Thingamajigs section?

或者，我可以做这样的事情吗?

Alternatively, can I do something like this?

Thingamajigs
============

.. toctree::
   :maxdepth: 2

   Overview          <-- refers to Overview section in same file
   foo
   bar
   baz

Overview
++++++++

Thingamajigs are fun

推荐答案

节标题层次结构很简单遇到的顺序.因此，您的 ==== 下划线设置标题(H1")，++++ 下划线设置 仅此页面 的副标题(H2").取决于您所追求的布局...

The section headings hierarchy is simply the order as encountered. So your ==== underline sets the title ("H1") and ++++ underline sets the subtitle ("H2") for this page only. Depending what layout you're after...

A.也许你想要一个目录"部分作为概述"的兄弟部分(都在Thingamajigs"父级中)，因此插入一个新的 H2 部分标题:

A. Maybe you wanted a "Table of contents" section as a sibling of the "Overview" section (both within "Thingamajigs" parent), so insert a new H2 section heading:

Thingamajigs
============

Overview
++++++++

Thingamajigs are fun


Table of contents
+++++++++++++++++

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz
    

B.或者也许您不想要概述"在部分标题层次结构中，所以用不同的方式突出显示它:

B. Or maybe you don't want "Overview" in the section headings hierarchy at all, so highlight it by a different means:

Thingamajigs
============

.. admonition:: Overview

    Thingamajigs are fun

.. toctree::
    :maxdepth: 2

    foo
    bar
    baz
    

C.或列出此页面内的标题层次结构，与外部页面分开:

C. Or list the headings hierarchy within this page, separately from external pages:

.. contents:: In this page
    :local:

.. beware, that contents directive must appear before any heading hierarchy

Thingamajigs
============

.. toctree::
    :maxdepth: 2
    :caption: In other pages
    
    foo
    bar
    baz
    

D.或者完全按照上一个示例所示进行操作:移动概览"内容输出到一个单独的 ReST 文档，并将其名称包含在 toctree 指令正文中.

D. Or do exactly what your last example showed: move the "Overview" content out to a separate ReST document and include its name in the toctree directive body.

这篇关于结合内联部分管理 Sphinx toctrees的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！