Add new options for moving the toctree

[topiolli]

Subject: Add raise_level and index options to toctree

Sphinx currently places toctrees as children of the current nesting level. This is not always the desired behaviour especially with the hidden option. The ralse_level option lets one to move the toctree up. The index option lets one to adjust the position of the toctree e.g. by moving it last.

This fixes the problems reported in the links below but does not change the semantics of hidden.

#3622
http://stackoverflow.com/q/25276415/102441
http://stackoverflow.com/q/39110429/102441

Feature or Bugfix

• Feature
• Bugfix (the fact that hidden toctrees are always children of the current level sometimes looks like a bug)

[topiolli]

What went wrong? I got zero feedback in three months and now you simply closed the pull request. I assume there are valid reasons for the rejection, but I feel disappointed that you did not bother to even comment on this. Could you do me a favor and provide a little background for the decision?

[sidneycadot]

Hi @topiolli,

I tested tour approach for toctree massaging. It works nicely for the HTML backend, but somehow it messes up with the LaTex backend. See #3622 (comment) for a bit of discussion.

I think that your basic approach is better than the #3622 approach, since it doesn't require that the toctree be put at the top of the page.

To satisfy the LaTeX backend, it may be better to somehow patch an earlier stage of Sphinx. In a way, the problem you're solving is one of parsing: instead of (section (section (section)) (section toctree)) you want to to be able to parse the document as (section (section (section)) (section) toctree). The problem with RST, the language is that it doesn't provide "closing brackets" for its heading sections. So to disambiguate a choice must be and has been made: the toctree lands below its direct heading successor.

Perhaps the final answer to this nonsense lies in making the parser a tad more powerful.

I am astounded by the way that this issue doesn't have traction. For me sphinx is next to useless as a documentation tool if it cannot support this extremely obvious usecase. But it seems that few people even acknowledge that there is a problem. Very strange.

[sidneycadot]

But then again, maybe the problem is something else.

I am currently working on this:

https://pydwf.readthedocs.io/en/latest/index.html

Now the structure of the clickable ToC pane in the left hand of the screen is just what I want, however the structure on the landing page (linked above) is all over the place.

Perhaps a second data-structure is maintained for those two ToCs?

It seems as if the LaTex page 2 ToC and the start-og-document HTML ToC are incorrect in precisely the same way.

Pffffff what a mess.

[topiolli]

@sidneycadot, thanks for trying it out. I did not test the other back-ends as my docs (https://doc.visionappster.com/) have so much html-specific stuff that they wouldn't work anyway. Breaking the LaTeX backend is a valid reason for rejection, although you were the first one to provide that insight to me.

Rejecting the pull request without explanation most likely means that the maintainers don't consider this an issue. And since my patch fixes the the problems for my use case, I'm happy using my own fork for the time being. Trying to push with a rope isn't worth the effort. If you have time to find out what's wrong, feel free to suggest improvements. There are others who would benefit as well.

[mgeier]

@tk0miya might have closed this inadvertently while deleting the 3.x branch. Normally he doesn't close PRs without comment.

[sidneycadot]

Hi,

And since my patch fixes the the problems for my use case, I'm happy using my own fork for the time being.

I'd be willing to do that too, but I need to be able to build my docs on readthedocs.io, and they are using a stock Sphinx.

I have tested your patch there by monkeypatching sphinx at runtime (horrific I know) and that works, but not for my needs which includes rendering to PDF. That's still broken.

There are others who would benefit as well.

Yes. I remember starting out with Sphinx and almost immediately hitting this bump, where the syntax supported by Sphinx doesn't really match my mental model of what such a tool should be able to do. There's quite a number of people like you and myself all over the web who are bitten by this, but that doesn't seem to translate in any kind of urgency.

I've been looking into the docutils RST parser that Sphinx uses. In many ways I think the best solution would be to introduce a construct there, probably a directive, that would indicate "go up one level from the current heading level". If that's present, it would provide the perfect solution. I'll prod their mailing list to see if I can get them to pay attention. Or perhaps they can explain to me how to implement such a directive even though they don't recognize the need.

[mgeier]

@sidneycadot

I need to be able to build my docs on readthedocs.io, and they are using a stock Sphinx.

You should be able to specify an arbitrary Sphinx version in requirements.txt, including using a branch of your own Git repo. I'm sure that's somewhere in the RTD docs, but I've also documented a similar thing over there: https://nbsphinx.readthedocs.io/en/0.8.5/usage.html#Using-requirements.txt

[sidneycadot]

Whoa, I didn't know I could even import dependencies from Github, that surely beats my in-flight patching approach. Thanks for the head-up.