rtd theme shows expand bullets on local instance, but not readthedocs.org

[hach-que]

Locally:

On readthedocs.org:

Note the lack of the "[+]" icon on readthedocs.org. This icon is valuable to indicate what items have additional content underneath them (as opposed to being a single page).

This can be seen at https://protogame.readthedocs.org/en/latest/assets/index.html.

[gregmuellegger]

The reason for this is, that the live version doesn't load the full TOC into the sidebar. I'm not 100% sure why this is the case, but I assume it's to save on loadtime as the TOC can get really huge if you create lots of subheaders.

@ericholscher @agjohnson maybe you can shed some light on this and you might already have a plan in mind on how to fix this?

[agjohnson]

There is a theme option collapse_navigation, which determines if the sidebar nav should be global or local. We set this to False by default to speed up large toctrees. Setting this to true should show all level 1 navigation items as expandable.

[hach-que]

So I tried setting that theme option: https://github.com/hach-que/Protogame.Docs/blob/master/conf.py#L115, but it didn't make the bullet points show up: https://protogame.readthedocs.org/en/latest/index.html

[gregmuellegger]

@hach-que that happens because of how we have to bend Sphinx in order to use the sphinx_rtd_theme instead of default. In your case we override the html_theme_options with code that gets appended to your conf.py prior to a build.

You can see the code that modifies your settings here: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl#L62
In order to make it work, you could change the line where you set html_theme = 'default' when on_rtd is True to something like:

html_theme = 'sphinx_rtd_theme'
html_style = None
html_theme_options = {'collapse_navigation': True}
using_rtd_theme = True

That should trick our checks for the default theme and allow you to define
proper html_theme_options.

[gregmuellegger]

You can now examine the generated conf.py file with the merge of #1651.
That should make it easier to debug on how you can override the setting properly. Closing this ticket for now. Feel free to respond if it still doesn't work for you.