Notification: allow theming

[Cadair]

Hello,

I was looking into how I could best integrate the new version notification with our theme (a sub-theme of pydata) and was hoping you could help me, my js skills are not the sharpest.

What options exist for customising the html or the css for the notification popup? Because of the whole shadow DOM setup, it wasn't clear to me the best way to inject my own styling from the "outside", any pointers to get me going would be appreciated.

[humitos]

Hi @Cadair 👋🏼 . We don't currently support any other customization of the addons besides the ones that can be done using the WebUI from the new dashboard (https://app.readthedocs.org), under the project's settings and some CSS variables to change the size of it, like --readthedocs-flyout-font-size and similar ones.

We've discussed this topic a lot in #51 and other internal conversations, but we haven't reach to an agreement about how to build it in a way that users can easily customize the web components we expose to users and we can maintain that customization over time without being blocked on adding improvements/features to them.

Currently, the only way to to implement the notification addons with a custom position and style to match the style and layout of your theme is implementing the notification by yourself using the data exposed by Read the Docs. This data can be consumed by subscribing to the readthedocs-data-ready JavaScript event and render the notification's HTML by yourself.

This is just a quick, dirty and untested example of what I'm describing:

document.addEventListener("readthedocs-addons-data-ready", function(event) {
  const config = event.detail.data();
  let notification;

  if (config.versions.current.slug === "latest") {
    notification = `
<div>
  <div class="title">
    This is the <span>latest development version</span>
  </div>
  <div class="content">
    Some features may not yet be available in the published stable version.
    Read the <a href="/en/stable/">stable version of this documentation</a>.
  </div>
</div>
`;
  }

  // Inject the generated flyout into the body HTML element.
  document.querySelector("[role=main]").insertAdjacentHTML("afterbegin", notification);
});

Let me know your thoughts about this and if this information is useful to you. I'd really appreciate your feedback on this.

[Cadair]

Hi @humitos thanks so much for your response. That approach makes sense, but how would it interact with the default one? Would users of my theme have to disable the original one in RTD settings?

I am both looking at dealing with this upstream in pydata and also just quickly in my own theme, so I am trying to figure out the best solutions from all perspectives. I did read through #51 but will have another look with the extra context.

[humitos]

how would it interact with the default one? Would users of my theme have to disable the original one in RTD settings?

Yes. Users should be able to decide whether to use the default notification from Read the Docs (unchecking a setting in the WebUI) or the customized one from the theme (e.g. using a theme config like notification_latest = True|False or similar).

We did this for our own theme and the flyout where we created a flyout_display config to allow users to disable the flyout from the theme if they want: https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html#confval-flyout_display

[Cadair]

ok, that makes sense, and reading back through #51 I see how and why it's like that.

It feels kind of unsatisfying from the theme developers perspective to have to reimplement the addon, and also from the users perspective to have to config the theme and the addon through the webui. That last point is particularly interesting for SunPy where we have a number of subprojects in RTD and these are all configured via a template, however, we can't template the addons settings so it's on one of us to go into the web ui for everything rather than put it the RTD config file for example.

I shall have a crack at writing some js in the pydata theme to display the version notification and see how it feels. Thanks!