sphinx-doc / sphinx-doc/sphinx

Extension template doesn't have access to updated HTML context?

Open
#7,086 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:html type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

I am developing an extension that includes some Javascript that is configurable based on the user's configuration input. The user should configure the extension with a key in conf.py, and then the value for this key needs to be inserted into a javascript file in the _static directory of the extension. Here's what I'm doing:

First I've defined a function that updates the context based on a config value.

def add_to_context(app, pagename, templatename, context, doctree):
    context['copybutton_skip_text'] = app.config['copybutton_skip_text']

Then I've added a new configuration key and connected the function to update
the HTML context:

def setup(app):
    app.add_config_value("copybutton_skip_text", ">>> ", "html")
    app.connect("html-page-context", add_to_context)

Finally, in my extension, I have a "templatable" javascript file (say, myjavascript.js_t). Inside I am trying to insert the variable like so

var skipText = "{{ copybutton_skip_text }}";

However, in the final rendered js file (myjavascript.js), the result is
always empty (e.g., var skipText = "") no matter how the value is configured.

I can confirm that default HTML context keys are inserted properly (e.g. docstitle)
so it seems like the HTML context update step isn't in effect when the extension JS file is being run through the template system.

Any idea why this would be? Am I doing things in the incorrect order or something?

If it's helpful, here's the PR where I am trying this out: https://github.com/choldgraf/sphinx-copybutton/pull/58

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the extension's setup(app), add_to_context, and html-page-context handler, then inspect how the _static .js_t file is rendered. Reproduce the configured-value case described in the issue and compare it with the default docstitle behavior; done means the configured value appears in the generated myjavascript.js.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.