问题
I'm trying to learn how I can manage a toctree element that is located in the same file as other content.
Suppose I have a thingamajig.rst chapter that looks like this:
Thingamajigs
============
.. toctree::
:maxdepth: 2
foo
bar
baz
Overview
++++++++
Thingamajigs are fun
When I render it --- foo/bar/baz have their own .rst files --- it looks like this:
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
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
回答1:
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. 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. 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. 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. 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.
回答2:
The exact specification given in the question can be satisfied, but not without significant issues that require workarounds.
Is there any way to have my toctree after the Overview section, but located under the Thingamajigs section?
By placing a toctree inside the Overview section your are placing all of that toctree's "Entries" (.rst files) inside that section and thus below that level in the section hierarchy.
However, a document must be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that hierarchy.
Pacing a toctree outside its pretended section will impact 1) "navigation", 2) "numbering" and 3) "depth".
First step of the workaround:
You can declare a toctree with the :hidden: option exactly where you want it -inside the Thingamajigs section- thus having 1), 2) and 3) working as intended. Sphinx will process the entries in the first toctree declaration, so afterwards the toctree declared inside Overview won't affect 1), 2) and 3) because the .rst entries were already processed.
The result:
Corresponding thingamajigs.rst:
Thingamajigs
============
.. toctree::
:hidden:
foo
bar
baz
Overview
++++++++
Thingamajigs are fun
.. toctree::
foo
bar
baz
The above satisfies the problem exactly as it was specified in the question.
(Sphinx will issue warnings because the same .rst file was included in more than one toctree, but they aren't errors just warnings.)
Second step of the workaround:
However, now comes a surprise! If you go one level up, to the .rst containing the toctree that has thingamajigs.rst as an entry, you'll find the :hidden: toctree wasn't rendered, and instead the visible toctree is rendered "in place" (out of order):
The result:
Corresponding level_2_toctree.rst:
***************
Level_2_toctree
***************
.. toctree::
fill_tree1
fill_tree2
fill_tree3
fill_tree4
thingamajigs
Although 1), 2) and 3) are working (in terms of the toctrees retaining their functionality), this leaves us with a problem: fixing the rendering order in parent toctrees. The obvious solution is to repeat the original lower level toctree "as is" inside a bullet list and adding references targeting the sections:
The result:
Corresponding level_2_toctree.rst:
***************
Level_2_toctree
***************
.. toctree::
fill_tree1
fill_tree2
fill_tree3
fill_tree4
.. toctree::
:hidden:
thingamajigs
- :ref:`5.5. Thingamajigs <target_thingamajigs>`
.. toctree::
foo
bar
baz
- :ref:`5.5.4. Item Overview <target>`
.. toctree::
foo2
bar2
Notice you would have to add hyperlink targets to the original thingamajigs.rst.
.. _target_thingamajigs:
Thingamajigs
============
.. toctree::
:hidden:
foo
bar
baz
.. _target:
Overview
++++++++
Thingamajigs are fun
.. toctree::
foo
bar
baz
Third step of the workaround:
But this has another problem, the HTML theme may have different CSS styles for bullet lists and toctrees, both are processed as different HTML elements (examine the source).
One solution would be to wrap the block including the 2 delimiting references in a reST directive (a container) that allows for custom styling as to make the block "blend in" with the remaining toctree. However, you would have to propagate this customizing at every step of ascending the toctree chain. This does provide a general solution as "proof of concept" for having a "portable toctree" placed out of context. The two main drawbacks are having to manually refactor the hyperlink numbering, and the overhead and expertise required to customizing the CSS.
No more workarounds:
Consider the Sphinx toctree directive and the reStructuredText contents directive are very different. While the whole point of the toctree is chaining .rst files together, the aim of the contents directive is providing a nice table of contents of the .rst file (or the section) it is in.
Try the useful :backlinks: option of the contents directive, by clicking back and forth between the upper index and the corresponding section of its documentation.
"Ideally" the best way to avoid workarounds is using the right tool for the job at hand.
The third option that's a complement to the above two is using a bullet list made of hyperlink targets. It's flexible and allows to mix links both internal and external to the .rst file containing the bullet list. Plus it doesn't interfere with the automatisms of the toctree or the contents directives - which depend on sections. The second step of the workaround includes both of the bullet lists' essential elements.
I'm trying to learn how I can manage a toctree element that is located in the same file as other content.
Looking at toctrees in the official Python documentation one example, or another example you see the "Flat, Simple, Special cases..." from the Zen of Python reflected. Most prominent documentations I've seen chose simple toctree layouts.
Without changing the specified presentation, the most efficient solution is using a bullet list of references to hyperlink targets inside Overview instead of the toctree.
回答3:
Others have commented about toctree and contents, so I won't repeat them.
You can do a hack with the raw directive.
Thingamajigs
============
.. raw:: html
<h2><span class="section-number">1.1. </span>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
.. Overview
.. ++++++++
Thingamajigs are fun
.. toctree::
:maxdepth: 2
foo
bar
baz
To get the HTML that I used in the raw directive, I started with "Overview" and its underline to generate the HTML. Next I copied it from the generated HTML and pasted it as you see above, indenting it under the raw directive. Finally I commented out "Overview" and its underline. You can season your raw HTML to taste.
Personally, however, I do not see the point of having both a title, immediately followed by an "Overview" or "Introduction" heading, immediately followed by the content of the overview or introduction. I would remove the heading and simply display the desired content. It's obvious what it is, so why does it need a heading?
来源：https://stackoverflow.com/questions/59397527/managing-sphinx-toctrees-combined-with-inline-sections