Don't show toctree hidden pages in left nav sidebar

[sarina]

Hi,

Is there a way to not show certain elements in the toctree in the left sidebar? Particularly we have some stuff in a hidden toctree that we don't want shown in the left sidebar.

In general it would be great to be able to exclude pages from the left sidebar nav, because space is at a premium.

Example: https://docs.openedx.org/en/latest/site_ops/install_configure_run_guide/index.html

The three "Deprecated" pages that appear in the left sidebar are in a hidden toctree that (correctly) don't appear on the index page.

Thanks so much for any pointers or advice, I couldn't find anything in the docs.

[trallard]

@sarina Thanks for opening this issue. I do not have an immediate response for you, but we will need to investigate.

@gabalafou would you be able to have a look at this and see if this can be reproduced?

[OriolAbril]

I generally use the hidden option of toctrees when I want them to show on the side navbar but not on the page itself, so this change would be extremely disruptive for documentation built with the theme in mind and relying on this. To me this not only isn't a bug but it is a critical feature.

The description in the sphinx docs says the following:

A hidden toctree only defines the document hierarchy. It will not insert links into the document at the location of the directive.

This makes sense if you have other means of navigation, e.g. through manual links, HTML sidebar navigation, or if you use the :includehidden: option on the top-level toctree.

I interpret that as: when using hidden don't show the links in the place on the page where the directive is placed but do show them on other document hierarchy views like the sidebar.

For pages I don't want to show anywhere I use the orphan file-wide metadata or if they are too many pages and/or pages generated automatically the sphinx-remove-toctrees extension. @sarina do you think either of the two would fit your case?

[sarina]

@OriolAbril I appreciate the input & your perspective. I am on vacation now but I'll dig into this next week.

[gabalafou]

@sarina, you may have to take this issue to the Sphinx Book Theme, which is built on top of this theme. This theme already supports what you want via sidebar_includehidden, which is one of our theme configuration options.

Removing the problem with PyData Sphinx Theme

In fact, if I build the docs for openedx.org by adding the following lines to the bottom of Open edX's conf.py file:

# conf.py 

html_theme = "pydata_sphinx_theme"

html_theme_options = {
    "sidebar_includehidden": False
}

Then when I load the same page you linked above, the sidebar table of contents matches the index page—specifically, neither of them includes the hidden (deprecated) portions, as the following screenshot shows:

Pinpointing the problem in Sphinx Book Theme

I can take this one step further and pinpoint exactly where your problem occurs in the Sphinx Book Theme source code. It's on line 20 of the SBT sidebar nav template. The template passes includehidden=True to the generate_toctree_html() function. Compare that with our theme's equivalent sidebar nav template, which passes the theme configuration value to the function.

Possible Complications

One thing you should be aware of—you may have to do some playing around with the toctree directive on your site. It looks to me that you're using the :hidden: parameter in at least two different ways: one, to hide deprecated pages from appearing in the table of contents and two, to avoid duplicating links on the same index page. Your sidebar nav currently relies on Sphinx Book Theme passing includehidden=False. The moment you switch that to true, you will lose, for example, the "User Home Pages" section of the sidebar table of contents:

Conclusion

Since PST already supports the ability to NOT include hidden TOC trees, I'm closing the issue.

[gabalafou]

As I was going through some issues I realized that I closed this is "completed" but I'm guessing I should have closed this as "not planned"?

[drammock]

As I was going through some issues I realized that I closed this is "completed" but I'm guessing I should have closed this as "not planned"?

yeah "not planned" is better IMO but I'm not too fussed about it; we don't really rely on the distinction being made consistently (e.g., for maintainer metrics or something)