User API: communicate with the library

[humitos]

There are many integrations that will require some user configuration. For example:

• HTML templates: there are some integrations that use HTML templates to render (e.g. flyout, non latest version warning, external version warning). We need to design a way users can tell the library what HTML template to use or giving them a way to replace ours completely (as flyout is doing via #readthedocs-embed-flyout) ¹
• Functions with logic: we are using semver to decide if the current version is the highest. However, the user may be using CalVer or a custom versioning pattern. We should allow users to tell us what's the "function that returns the highest version from a list of versions" that we should execute.
• Element query selectors:
  • what's the selector for the main content?
  • what's the content selector to apply tooltips to the inner links?
  • what's the selector for the search-as-you-type be triggered?
  • etc
• Data for functions:
  • default filter for search
  • extra filters for search
• Tooltips:
  • should we apply them to all the content?
  • should we only apply them on a specific selector? (as we currently do with .hoverxref class)
  • should the doctool generate HTML tags with this specific selector?
  • should we try a defined selector and fallback to the main content if not found?

Note there may be more things to consider here, but I wanted to mentioned the ones that I found while working on this library. I'd like to define the pattern first, since once we have that defined we can easily add more. I'm looking for "the standard pattern to communicate with a js library from the browser", basically.

Also, it's worth to mention that some of them can be converted to conventions (e.g. some selectors) but we need to discuss and agree on them anyways.

Footnotes

1. this work may require writing a policy that users should follow since they can overwrite our templates completely. We may want to "enforce" projects to show "Hosted by Read the Docs" or similar in the flyout, for example. ↩

[humitos]

There were some progress in this direction. I'd say, mainly in my understand of what we need from the user and how this could work in the js world. With the addition of WebComponens, CSS variables and others it's a lot more clear to me how people will interact with this library in some of the required ways. There is no decided made already about this, but I guess that:

• we will expose some CSS variables
• users can define CSS variables if they want to change a particular style from the UI
• users will use data- attributes or specific CSS classes to specify pre-defined styles for our addons
• we will define some custom WebComponents
• people can place the HTML component whenever they want in the HTML; if there is one present, we won't include "the default one"
• to customize HTML structure for those WebComponents we will probably use <slots> that users can override with the content they prefer
• to customize "logic" of the webcomponents we could use data- attributes ¹ to override some "exposed functions"

This my mental map currently. Does this make sense to you @agjohnson?

If possible, addons will always have "nice defaults" and conventions. However, there are some that may require specific selectors (e.g. docdiff needs to know the "main" tag where the content is). Would these also be data- attributes? In the specific case of docdiff, it may not make sense since it does not require a HTML tag to be inserted, so it may need to be a js call? Like readthedocs.addons.docdiff.init({selector: "[role=main]"})?

Footnotes

1. is there a better way to communicate this logic customization? I image something like <readthedocs-version-banner data-versioning-type="semver"></readthedocs-version-banner> ↩

[agjohnson]

For the most part, that is what I'm aiming for as well 👍

Some minors notes:

to customize HTML structure for those WebComponents we will probably use

I've only played lightly with a pattern to customize the template, and haven't yet experimented with slots yet. So, this is a bit of a gap in my understanding, but I think it seems like a path forward.

For now, we can also take the position that we're not providing this level of customization and users would have to roll their own implementations if ours don't fit their needs exactly.

I haven't yet determined if it's possible, but this would be nice from an author's aspect:

<readthedocs-notification>
  <!-- template goes here -->
  <div class="bootstrap-classes etc">
    <h1>${this.title}</h1>
    <p>${this.message}</p>
  </div>
</readthedocs-notification>

to customize "logic" of the webcomponents we could use data- attributes

Web components don't need to use data attributes even, as the reason for data attributes in the first place is to avoid collision with native element attributes, or at least to provide some distinction between native/custom attributes.

For a web component, all attributes are custom, so we'd instead have something like <readthedocs-notification version-pattern="semver"></readthedocs-notification>

However, there are some that may require specific selectors (e.g. docdiff needs to know the "main" tag where the content is).

Great points. I haven't had time to reason about on this question/pattern yet, so have to focus on this at some point next.

One thing I'm considering for some amount of configuration for these features is that some of the individual component configuration will come from perhaps the dashboard UI. I'd agree that a web component isn't a good fit for doc diff, as it affects the whole page and not one element.

I could see us having a project settings tab for "Pull requests", and the option to enable pull requests is moved there, but also the doc diff configuration is moved into the same view. This feels intuitive. For example, it would have a form:

☑️ Enable pull request builds
☑️ Show documentation diff by default on pull request builds
☑️ Hide removed content on documentation diff by default

But the programmatic approach in addition to this is also probably something we want -- though I'm less certain of the pattern there just yet.

[humitos]

This issue is also related to #51