Option to move page contents into the sidebar?

[exelotl]

Hey, I've been working (well, experimenting locally) on a RST conversion of a tutorial in which each chapter is a single page with several headings.

I'd like to globally remove the right-hand side contents, and take advantage of the main folding sidebar instead, for example it would show up as:

• Introduction to Tonc
• GBA Hardware
  • Meet the GBA
  • GBA specs and capabilities
  • Memory Sections
• Setting up a development environment
• My first GBA demo

I don't have a toctree per-chapter so I can't get this folding appearance as-is. I'd prefer not to split each chapter into several documents, and sadly this decade-old issue to allow relative links in the toctree is still open 😢

I guess it would use just one level of folding, similar to what already exists, not several levels like in ReadTheDocs, as that gets overwhelming fast... Is a global toggle for this something that could work or would it be against the design of the theme?

[pradyunsg]

No, there isn't any (supported) way to do this.

Separating the page content hierarchy and site structure was an explicit design goal.

[exelotl]

That's totally fair, the theme is wonderful so I'm more than happy to live with that decision :)

[leycec]

Necrobump. As the @beartype maintainer, this was a deal breaker for @beartype's RtD-hosted documentation.

What Furo's current approach really means is that Furo silently ignores standard Sphinx settings and directives. That's bad – like, mega-hyper-super bad. That is the worst possible approach that Furo could have taken, really.

If you're going to intentionally ignore vast swaths of a decades-old API documented across multiple languages, please at least have the common courtesy to emit a visible error IN ALL CAPS grotesquely highlighted in blinking red explaining what sacred ground you are transgressing upon and why you are committing that transgression. That's exactly what Furo currently does with Sphinx's standard contents:: directive, which you:

1. Loudly ignore by default.
2. Allow users who think they know better to override with a :class: this-will-duplicate-information-and-it-is-still-useful-here. setting.

That's fine. That's good. That's also what Furo should be doing here. Effectively defaulting to :titlesonly: and :maxdepth: 1 for toctrees is fine. Silently forcing those same settings without user consent is not fine.

I struggled with this in futility for several hours on a Saturday evening before eventually realizing that I wasn't to blame here; Furo was to blame, because Furo is intentionally ignoring my :toctree: directives for purely subjective, opinionated reasons that honestly don't even hold up to scrutiny. Forcefully flattening the normal hierarchical structure of navigation sidebars doesn't actually improve navigability; it blatantly harms navigability, because now users have no means of directly navigating from the root document to leaf (sub)sections contained in child documents of the root document.

In short, this discussion saddens me. Furo's clean and reactive CSS is a beautiful sparkly thing of wonder and delight – but the cost is subjective opinions over which users have no control and aren't even informed. The cost is too high. Cue sad cat. 😿

[pradyunsg]

Hi @leycec, I see you’ve had a frustrating day, sorry about that! It’s generally preferable to not “necrobump” since the title for a new discussion makes it easier to look things up. :)

Separating site structure vs page content means that certain structures that work well on other themes do not work well on Furo, and I think that’s fine. Trying to cover every edge case will make things worse for everyone IMO.

:maxdepth: 1

This is not what is done in Furo. It is absolutely possible to have nested content based on the toctree directives. The main restriction is that they need to be at the root of the document, rather than within a subsection. That’s because Sphinx will silently trim those when you pass titlesonly. Furo is enforcing the use of titlesonly to separate the two different concepts: site structure and page contents.

---

I’m a bit annoyed at the tone, but keeping that aside by assuming good faith, I’m thinking of what could be done to make this experience for you go differently: Would it have helped if Furo had a documentation page describing how it handles the sidebar content, with examples of various things that work and don’t work?

[pradyunsg]

Closing this thread given the lack of a response here.