html_theme_options not applied

[robredpath]

Details

• Read the Docs project URL: http://docs.openreferral.org/en/add-project-docs/hsds/logical_model/

Expected Result

After adding:

html_theme_options = {
    'titles_only': True
}

to my conf.py, I expected the left-hand menu to render without adding page headings as sub-menu items

(I'd like to be able to configure those sub-menu items through toctrees so that I can link to second-level content)

Actual Result

On-page headings are added to the menu as sub-menu items.

Notes

I don't know RTD's code at all, but I did notice that this line seems to override any html_theme_options set.

I also don't know if I should expect to be able to configure this on hosted RTD!

[humitos]

Taking a look at your docs at http://docs.openreferral.org/en/add-project-docs/hsds/schedules/ I see there is subheadings in the navbar. See:

[robredpath]

@humitos thanks for taking a look at this.

As I understand it, 'titles_only': True should stop subheadings appearing. Or is that incorrect?

[humitos]

Hrm, good point. I suppose that if you use False, it will show subheadings in all the elements from the navbar, and using True it uses only the titles in all the elements but in the current page.

The documentation of this config is at https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-titles_only and it's not super clear. cc @benjaoming @agjohnson

[benjaoming]

The titles_only option is passed straight to a Sphinx function toctree

https://www.sphinx-doc.org/en/master/templating.html#toctree

As I understand it, 'titles_only': True should stop subheadings appearing. Or is that incorrect?

That is correct!

I don't know RTD's code at all, but I did notice that this line seems to override any html_theme_options set.

I think you found the cause of the issue :) I tried to show you how you can change your conf.py so RTD doesn't get "confused"... what's confusing is that html_theme_options is configured but html_theme isn't. So basically, you just need to set html_theme and then html_theme_options won't be overridden.

I recognize your pattern comes from "old days", but it's perfectly fine now to define html_theme.

Good luck!

[benjaoming]

P.s. feel free to re-open if the issue persists!

[robredpath]

Thanks so much! The project I'm working on was set up in 2016 and all attention has been on the content rather than the docs setup, so it's not surprising that we've ended up with a mix of old and new conf. Time to get that fixed!

[benjaoming]

I'm pretty sure you'll find some new benefits from updating the setup! Out of curiosity, can it be noted that Read the Docs has successfully built your setup for 6 years without breaking? :)

[robredpath]

can it be noted that Read the Docs has successfully built your setup for 6 years without breaking?

Ha, it absolutely can - that's some impressive resilience and backwards-compatibility right there!