Hi Luc,
As an example, this is a page of a project I am working on:
https://pydwf.readthedocs.io/en/latest/pydwf_api/DwfLibrary.html
This page talks about a certain class in broad terms, then dives into
details on some sub-topics in pages that follow. In the ToC I want those
sub-topics one hierarchical level below the introductory section. I want
both the intro and the sub-topics on their own pages.
Currently I do this by a hack: not having headings in the intro-page. I now
use ::rubrics in the intro page, and a hidden ToC at the end of the intro
page. That gives me the ToC structure I want, at the cost of being unable
to use any headings on the intro page. The use of ::rubric's is a way to
avoid that.
I could also do this -- every line a separate rst page. I think this is
what you suggest:
* ToC superpage
* Overview section B with headings and all.
* Detailed section B1
* Detailed section B2
However, this is not what I want. The sections B, B1, and B2 are at the
same hierarchical level here (I want B1 and B2 below B in the ToC); and a
ToC superpage will be generated that I really don't want, either in HTML or
in in PDF.
> It's more intuitive for the reader when every page is *either* a node of
the ToC *or* a content page with sections.
I don't agree in general. There are many fine educational books and manuals
that do what I try to achieve. Let's agree to disagree on this and discuss
if/how it could be done.
I would like to ask the inverse question; suppose you *have* a page with
both headings and a ToC. I don't see any case where the useful thing would
be to add the ToC at the level determined by the level where the ::toctree
happens to sit in the first page. Suppose the text preceding the ::toctree
happens to end at subheading-level 3, the ToC entries will be inserted one
level below that, which is undesirable in any situation I can think of.
Having googled for this issue a quite a bit prior to asking here, I have
seen that I am not the only one who was surprised by this. Only when I
started experimenting with a small project to figure out what was going on,
I started understanding what Sphinx is doing.
You end up with webpages recommending not to mix headings and ::toctree
directives on the same page at all
(eg
https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/MenuHierarchy.html),
without going into detail on the *why*, or if it is even sensible to have
to recommend such a policy. If in-page headings and toctrees don't mix,
then I feel it would be better to emit an error and refuse to render, than
to have the current behaviour where the toctree items are inserted one
level below whatever happens to be the heading level where the toctree
resides.
Best, Sidney
On Tuesday, May 25, 2021 at 7:40:19 AM UTC+2 Luc Saffre wrote:
> Yes, understandable. What I don't understand: why do you need the
> structure you are asking for? Can you give us a real-world example for your
> tree structure? Why don't you simply move the three sections from B into a
> separate page B0? It's more intuitive for the reader when every page is
> *either* a node of the ToC *or* a content page with sections. A third type
> of page is where you have section titles and each section contains a
> toctree (I use this when I have a toctree node with many entries but do not
> (yet) want to move them to separate toctree pages.
>
> Luc
>
>
> On 25.05.21 00:30, Sidney Cadot wrote:
>
> Hi Luc,
>
> Thanks for the suggestion!
>
> The problem with a normal* ..include* directive will be that I lose the
> separate pages for B1 and B2 in the HTML backend (and other backends that
> don't combine everything).
>
> When I wrote "I want to keep the 7 documents", what I meant to say is not
> so much that I want to hold on to the separate source documents; I want to
> make sure that individual HTML pages are generated for each of the 7
> documents. The *include* approach doesn't accomplish that.
>
> Cheers, Sidney
>
> On Monday, May 24, 2021 at 10:11:38 PM UTC+2 Luc Saffre wrote:
>
>> Did you try to .. include:: the two docs B1 and B2? In that case you must
>> also use the exclude_patterns
>> <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns>
>>
>> config option to tell Sphinx to exclude them from the build.
>>
>> Luc
>>
>>
>> On 24.05.21 20:52, Sidney Cadot wrote:
>>
>>
>> Hi all,
>>
>> I am having trouble getting sphinx to do what I want.
>>
>> I have 7 documents: index, A, A1, A2 ; B, B1, B2.
>>
>> The index has a toctree that lists A and B.
>> Document A has a toctree that lists A1 and A2.
>> Document B has three sections followed by a toctree that lists B1 and B2.
>>
>> This results in the ToC that I have attached as a picture.
>>
>> What I would like is that Document B1 and B2 are listed in the ToC at the
>> same level as the subsections of document B. In effect, I want the ToC
>> entries {B1, B2} to be direct children of Document B, just like {A1, A2}
>> are direct children of A.
>>
>> I want to keep the 7 documents; and I want to keep everything in the
>> order as stated.
>>
>> Is this possible? Or does the Sphinx parser and/or internal document
>> datastructure not allow this for some reason?
>>
>> Kind regards,
>> Sidney
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "sphinx-users" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to [email protected].
>> To view this discussion on the web visit
>> https://groups.google.com/d/msgid/sphinx-users/976e3827-35b5-4e72-ac1f-7e29da91f49bn%40googlegroups.com
>>
>> <https://groups.google.com/d/msgid/sphinx-users/976e3827-35b5-4e72-ac1f-7e29da91f49bn%40googlegroups.com?utm_medium=email&utm_source=footer>
>> .
>>
>>
>> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to [email protected].
>
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sphinx-users/4cfa2a5e-7b16-4ab6-9a1b-2729da549804n%40googlegroups.com
>
> <https://groups.google.com/d/msgid/sphinx-users/4cfa2a5e-7b16-4ab6-9a1b-2729da549804n%40googlegroups.com?utm_medium=email&utm_source=footer>
> .
>
>
>
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/sphinx-users/7eeed6b2-014b-40d3-96e1-b150dacc1910n%40googlegroups.com.
