Hiding certain parts of the documentation from the sidebar

[ma-sadeghi]

It seems that maxdepth directive is not respected in side bar. Here's my index.rst:

.. toctree::
    :maxdepth: 1
    :hidden:
    :titlesonly:

    installation
    basic_usage
    modules/index

And here's what it looks like:

[pradyunsg]

That’s intentional and an opinionated design choice I made. :)

Unlike other Sphinx themes, Furo is designed to provide the entire site tree in the sidebar. This makes it easier to navigate through the documentation as a reader (I can see exactly where I am), and it forces documentation authors to consider their site’s structure more carefully.

I guess a good follow up for this is: why do you want to hide some of the site structure from the user?

[ma-sadeghi]

Fair enough, I guess my case is very special and doesn't really apply elsewhere.

We have a section in our documentation called Examples with the following structure:

Examples
  Filter
    example_title_1
    example_title_2
  Generators
    example_title_3
    example_title_4
    example_title_5
etc.

The problem is that example_title_X is typically long and so, it clutters the sidebar. For this reason, we've created another toctree for Examples with proper headings that should be sufficient for navigating through examples.

So, basically, we want the sidebar to just point to Examples.html, excluding any children pages.

[pradyunsg]

Fair enough, I guess my case is very special and doesn't really apply elsewhere.

I disagree! Your use case is perfectly valid and matches uses what I've seen elsewhere. If it helps, I'll mention that I pushed back on adopting Furo on packaging.python.org for the same underlying issue, of too-much-stuff in the sidebar.

Basically, I'd consider these documentation structures to be "too complex for Furo". They're not bad or whatever; just incompatible with Furo's show-everything-everywhere approach.

I had to make a choice about whether Furo should well really work for 80% documentation structures, or work OK-ish for almost-everything.

I picked the former, with the plan being to write a sister theme that does work for larger documentation sets! That sister theme is in the pipeline, but it'll be a little while before that comes out. :)