Unable to get intended document organisation

[Sidney Cadot]

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

[Luc Saffre]

Did you try to .. include:: the two docs B1 and B2? In that case you must also use the exclude_patterns config option to tell Sphinx to exclude them from the build.

Luc

--
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 sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/976e3827-35b5-4e72-ac1f-7e29da91f49bn%40googlegroups.com.

[Sidney Cadot]

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

[Luc Saffre]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/4cfa2a5e-7b16-4ab6-9a1b-2729da549804n%40googlegroups.com.

[Sidney Cadot]

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

[Sidney Cadot]

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...

[Luc Saffre]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/4b5ca8de-0514-4f93-9e27-22b0c71773d8n%40googlegroups.com.

[Sidney Cadot]

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.