Awesome, thanks. The only thing I dread is that this particular PR has been lingering for several *years* now. It is still waiting for approval by @tk0miya.
For local doc builds I could just go ahead and apply the commits, but I want everything to render on the readthedocs infrastructure as well. On Wednesday, May 26, 2021 at 11:11:30 AM UTC+2 Luc Saffre wrote: > 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]. > > 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/c30566cf-9f72-49d6-abf5-42405bb71e2dn%40googlegroups.com.
