interface for adding extra template context

[davidism]

I've been working on porting Flask's docs to be built on RTD instead of our custom builder. Our builder has a separate JSON file with metadata about versions, and inserts it into html_context by combining each project's Sphinx config with a standard config. html_context can also be set on the command line with -A key=value flags. RTD's interface doesn't allow doing this yet.

While that version information is already available from RTD and just needs to be documented (#3482), it would still be nice to be able to specify additional template context using the web interface. One option is a text box that users can paste JSON in, then add html_context.update({{ extra_html_context|tojson }}) after RTD's default html_context.

[davidism]

@ericholscher mentioned this could be accomplished with a Sphinx plugin. However, this would require us to maintain a separate public package, make a new release of it with new context, and trigger RTD builds for all versions every time we wanted to change the global context, which is not very convenient. RTD directly supporting extra global context would be much nicer.

[ericholscher]

We currently support a user having a defined html_context in their conf.py. This can be generated with Python code, and doesn't require an extension. An example here: https://github.com/writethedocs/www/blob/master/docs/conf.py#L111-L114 -- I believe this is what you want?

[ericholscher]

We already call update on the existing html_context here: https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl#L130

I guess we could add additiona_html_context in YAML, but I'm not sure how this would be better than just having it defined in the conf.py?

[davidism]

The problem with it being in the code is that it's now tied to the version being built. The useful thing about the context is that it can be modified externally at build time.

[ericholscher]

I'm not sure I follow. Can you explain the exact use case?

[davidism]

Let's say we want to display the docs for Flask 0.10, 0.11, 0.12, and 1.0. If we want to display some standard information in the sidebar for each build, like links to each version, we don't want to have to go back to the 0.10 branch and update it so it knows that 1.0 was released. We want to inject the current list of versions as we build each one. The specific example with versions is already handled by RTD's context, but it demonstrates the idea.

[ericholscher]

Yea, this is actually a different problem on our side. We solve this in JavaScript by sending the data via the footer response. That is "v2" of #3482, where we give users access to that "realtime" project data in JS, so you don't have to rebuild all docs every time one version changes.

[ericholscher]

but I believe #3482 has what you want (a list of all active versions injected in template context on build)

[davidism]

Yes, for the versions use case, I've already got the information I need. This was a more general request for specifying global context at build time.

[ericholscher]

Gotcha. 👍

[humitos]

@davidism Hi! I'm about to start working on this issue and I would like to have some more feedback from your side to know if by implementing the design proposed in #3490 will fit your needings or there is something else missing from our side to achieve this issue.

[davidism]

That appears to be documenting RTD's internal context. It mentions adding context to conf.py, but the problem with that is discussed above. This issue is about adding a field to the RTD admin form to provide context that is independent of the version being built. The version information was an example, but this could apply to arbitrary context a project wants to add.

[davidfischer]

You primarily need this in order to get versions of particular projects correct? I believe this can be handled through the API like so:

https://readthedocs.org/api/v2/version/?project__slug=flask

That will get you all the versions and you can grab just the active ones if you want to. The active ones can be administered in the dashboard.

Let me know if this gets you were you need to be on this issue.

[davidism]

I don't need this anymore, although it may be useful to others. Perhaps it's more appropriate (or already present) in the YAML config?

You can close it if you'd like.