This PR seems to address this very issue: https://github.com/sphinx-doc/sphinx/pull/3622
But it somehow still in review after 3 or 4 years... On Tuesday, May 25, 2021 at 8:52:02 AM UTC+2 Sidney Cadot wrote: > 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/4b5ca8de-0514-4f93-9e27-22b0c71773d8n%40googlegroups.com.
