Override versions.html template for specific RTD functionality

[humitos]

Sphinx RTD theme uses a versions.html template to generate the version menu if READTHEDOCS variable is True. Since this is something specific to Read the Docs and that variable is going to be removed soon from the theme, we are overriding this template to maintain our current functionality.

Also, the static content generated in this menu is removed to avoid showing invalid links/data in case the AJAX fails for any reason. If this happen, the menu just won't show any information.

Related readthedocs/sphinx_rtd_theme#578

[humitos]

Overriding the templates only when using our own theme, but what would happen with derivated themes?

They will have the content of the versions.html that comes from our sphinx_rtd_theme instead of this one.

[agjohnson]

This is a good question. Maybe through some Sphinx internals we can determine if the theme in use extends our theme at some point? This sounds like a hard and error prone thing to determine though.

Ultimately, this might be a really good reason to keep this logic in our theme. The work required to replicate if READTHEDOCS is going to be substantial. Even if removing READTHEDOCS from our theme is technically correct, leaving it is the right thing to do.

[humitos]

This overrides works in the community and the corporate site without modification.

[agjohnson]

This implementation looks great, but I think you've raised another good reason to keep this logic in our theme.

[ericholscher]

I don't think this is a reason to not have this logic live outside the RTD theme. I think a reasonable approach would be:

• have the RTD theme use a block inside versions.html
• Override this block in our version of the template

I think that gets everything we want, unless I'm mistaken?

[humitos]

@ericholscher replacing the {% if READTHEDOCS %} by {% block versions %} is enough for your proposal?

The only problem that I see there is that the default content of that block is only valid for Read the Docs, then the user from outside RTD will need to override the template and use an empty block.

Just to be clear, is people building docs with READTHEDOCS=True outside Read the Docs platform?

• No: we could remove the whole content of versions.html file and replace it just by an empty block that we can override from the code of our sites
• Yes: although it's weird, we need to keep the default content of the block in the theme template

---

What about the other way around of what I proposed in readthedocs/sphinx_rtd_theme#578? Instead of having a READTHEDOCS and the theme option we could have the theme option used to replace the {% if READTHEDOCS %} and use the block that you proposed for the inner part of the HTML (replacing the current {% if theme_versions_menu %}).

With the above proposal, we will have:

• theme_versions_menu in False by default set in the theme: users outside RTD won't have a version menu rendered at all
• theme_versions_menu as True under Read the Docs (using the same append_conf method than in this PR)
• a template in Read the Docs to override the inner block with an empty block (in case we want to keep the default static block in the theme for some reason)

What do you think?

[ericholscher]

@humitos why can't we just allow people building outside of RTD to use their own versions.html similar to what RTD is doing, with their own logic?

[ericholscher]

I think maybe we should have a quick call about this to discuss. I think there are a number of competing priorities here, and it might be easier this way :)

[humitos]

We were talking to move this code into the extra_context block and use it in the corporate site.

[humitos]

I'm closing this as stale. I suppose that before we find a good way to do this we will end up having APIv3 with a flyout rendered via a JSON response.