I added my approval to PR https://github.com/sphinx-doc/sphinx/pull/3622
I had a look at the code changes. They make sense to me. I realize that this is probably difficult to cover by any test. Difficult to estimate whether this might disturb other users. But as the maintainer of more than 30 Sphinx websites I can say that if this change really would turn out to have unexpected side effects on one of my sites, I wouldn't get angry with the Sphinx team and actually even praise them for having jumped into this. Luc On 26.05.21 00:52, Sidney Cadot wrote: > 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] > <mailto:[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 > <https://groups.google.com/d/msgid/sphinx-users/4b5ca8de-0514-4f93-9e27-22b0c71773d8n%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/596abde3-8794-0913-d08f-f3a2d02580af%40gmail.com.
