Add styles based on the documentation tool #473

humitos · 2024-12-16T10:46:10Z

Use our heuristic to detect the documentation tool/theme and add specific --readthedocs-* CSS variables based on that for known tools/themes.

Reference: readthedocs/readthedocs.org#11849 (comment)

Use our heuristic to detect the documentation tool/theme and add specific `--readthedocs-*` CSS variables based on that for known tools/themes. Reference: readthedocs/readthedocs.org#11849 (comment)

agjohnson

I believe there is a better pattern here for dynamic styles. The Lit documentation probably suggests using classMap on the element, which could be another option. We've talked about avoiding classes for styling though, so I mostly lean towards a dynamic styles getter if it works easily.

src/flyout.js

humitos · 2024-12-17T10:25:36Z

I believe there is a better pattern here for dynamic styles. The Lit documentation probably suggests using classMap on the element, which could be another option

Yes. Is there are way to detect if the --readthedocs-* variables were defined by the user from JavaScript? The pattern that I want to implement here is:

Check if the user defined --readthedocs-* CSS variables
If those were defined, do nothing
If not, add a mkdocs-material CSS class to the element that redefines --readthedocs-*

Would that make sense?

I mostly lean towards a dynamic styles getter if it works easily.

I'm not sure to understand what this means. Can you expand o this?

humitos · 2024-12-17T11:00:15Z

I pushed a commit to what I understood it could be a better pattern for this. Let me know what you think.

agjohnson · 2024-12-17T18:06:13Z

I'm not sure to understand what this means. Can you expand o this?

Using a getter for styles property allows for conditional styles without adding class names.

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get#using_getters_in_classes

class SomeElement extends LitElemeent {
  static get styles {
    if (...) {
      return css`...`;
    }
    return css`...`;
  }
}

Would that make sense?

So, there is getComputedStyle: https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle

But it feels like better design to make this explicit and rely on existing CSS functionality for this. If we keep our rules low specificity, then user added rules can very easily be higher specificity -- and our styles are then overridden.

If not, add a mkdocs-material CSS class to the element that redefines --readthedocs-*

Using class names is a separate pattern, but also possible.

In general, a pattern I like is to (re)use element properties for CSS rules instead of classes. Element properties have specific purpose and update the Lit element properties where class names don't do anything but affect CSS styles. That is:

// The `tool` property affects the element reactive properties. This rule is specificity 0 1 1
readthedocsflyout[tool="docusaurus"] { ... }
// The CSS class is used only for styles, it doesn't affect the properties on the Lit element. Specificity 0 1 1
readthedocsflyout.tool-docusaurus { ... }

We should keep specificity as low as possible either way.

One wrench I'll give you though is that this is still just for readthedocs-flyout, and we probably don't want to have each element independently guessing the tool and applying styles. I'm guessing your initial attempt was closer to what you wanted. What I pointed out as the problem applying styles to html/:root from inside FlyoutElement is that this affects styles of other elements, and likewise doesn't apply these styles if the user has the flyout disabled.

So I think the styles you applied originally might be closer to what we want, we just shouldn't do this from inside a single element. This is something we should do a more global level.

I might still suggest a class/attribute selector approach here though, which leverages CSS functionality instead of hiding this logic from user in JS.

:root[data-readthedocs-tool="docusaurus"] { ... }
:root[data-readthedocs-tool="sphinx"] { ... }

This gives a clear attribute users can remove and we can avoid applying an attribute if a user already specifies an attribute or something like data-readthedocs-tool="manual".

src/flyout.js

humitos · 2024-12-18T14:50:15Z

One wrench I'll give you though is that this is still just for readthedocs-flyout, and we probably don't want to have each element independently guessing the tool and applying styles. I'm guessing your initial attempt was closer to what you wanted. What I pointed out as the problem applying styles to html/:root from inside FlyoutElement is that this affects styles of other elements, and likewise doesn't apply these styles if the user has the flyout disabled.

I was trying to keep things scoped by addon. That is, from flyout we should be defining only settings that affect the flyout (e.g.--readthedocs-flyout-* variables); without affecting other addons/elements.

Also, we can't do :root[data-readthedocs-tool="docusaurus] because that selector doesn't return anything since we are using shadow DOMs.

humitos · 2024-12-18T15:19:30Z

I pushed some changes that use tool=sphinx and tool-theme=furo attributes on readthedocs-flyout to define specific CSS rules based on the documentation tool and theme. I think I like this approach. Feedback welcome.

We will need to do the same for the other addons, where we we want to increase/decrease the font sizes. However, I'm happy to start with flyout for now and grow from there if we find this is the pattern we will stick to.

Based on #473

ericholscher

I like this approach with the CSS -- it feels really explicit which feels good.

ericholscher · 2024-12-18T17:52:10Z

src/flyout.js

@@ -31,9 +37,12 @@ export class FlyoutElement extends LitElement {
    super();

    this.config = null;
+    this.classes = {};


Seems we're setting this, and then overriding it on line 44?

Suggested change

this.classes = {};

Seems this is still an issue?

src/flyout.js

agjohnson · 2024-12-18T18:24:29Z

Also, we can't do :root[data-readthedocs-tool="docusaurus] because that selector doesn't return anything since we are using shadow DOMs.

If you need to manage these variables inside each addon then this is true, but what I was describing was applying these variables from the host DOM, at a global level. This is where users should/will be defining our CSS variables either way.

I was trying to keep things scoped by addon. That is, from flyout we should be defining only settings that affect the flyout (e.g.--readthedocs-flyout-* variables); without affecting other addons/elements.

I do think isolation makes sense, but we can still do addon isolation of styles/variables at a global level. We don't need to apply --readthedocs-flyout-font-size to only readthedocs-flyout or just one instance of <readthedocs-flyout>, that variable can be applied to html and still affect <readthedocs-flyout> the same.

Thinking more, we don't need an attribute or class on html. It feels like our doc detection rules should happen at a addon configuration/initialization and add the following variables at html:

// Styles applied for docusaurus
html {
  --readthedocs-flyout-font-size: 0.9rem;
  --readthedocs-notification-font-size: 0.9rem;
}

The easiest change for theme maintainers and users will be to add some CSS like:

// `html body` or `html html` is higher specificity than our rules at `html`.
html body, html html {
  --readthedocs-flyout-font-size: 2rem;
  --readthedocs-notification-font-size: 2rem;
}

This doesn't involve editing the doc tool theme HTML, so is the easiest control point.

Defining these variables inside the shadow DOM like you're describing might take precedence over host applied variables though, we should test this. This would make it hard/impossible for this easy control of these variables.

This all gives users/theme maintainers some way to control at least the styles applied by our magic, but it doesn't control or allow opt out from our magic detection. Attributes on each addon does accomplish this but it's rather cumbersome -- maintainers would have to define all our addons in HTML theme <readthedocs-flyout tool="custom" /><readthedocs-notification tool="custom" />....

humitos · 2024-12-19T13:10:22Z

By using selectors like html { --readthedocs-flyout-font-size: 0.65rem }, I'm only able to modify things exposed by --readthedocs-* variables; which is not enough in all cases. For example, I need to modify line-height for some of the themes/doctools and I'm not being able to. I think we will end up having one --readthedocs-* variable per addon per property if we follow this pattern 😞 (we already have one --readthedocs-*-font-size per addon)

I think that using --readthedocs-* is getting pretty complicated to allow us improving the look and feel of the addons while also letting users to modify them. We added them as an initial test to allow ourselves to document how to adjust the sizes of the addons because we noticed they didn't render properly everywhere (mainly on Material for MkDocs). However, this PR implements the better look and feel/styling automatically without user intervention. I'd propose to revert the idea of these --readthedocs-* variables and give us full control back over the addons until we figure it out a more generic pattern for customization in #51.

References:

Until then, this PR will give users a better UI/UX anyways since they won't have to do anything on their side. In other words, I'd like to give users the best default experience on their doctools/themes (at least the ones we known) for now (the proposal of this PR) and leave a more polished customization for the future.

ericholscher · 2024-12-19T17:24:22Z

I don't fully understand the implementation details here, but the goal I assume is having good defaults, but letting users be able to override them. If we have to choose only 1, I think good defaults is more important, since the initial experience for the user is most important, and getting that right is going to make adoption much more likely. However, it really seems like we should be able to support both, where we can set a default, and the user can override it?

agjohnson · 2024-12-19T20:28:54Z

or example, I need to modify line-height for some of the themes/doctools and I'm not being able to.

Line height should almost always be derived from font-size though, as a proportional value to the height of the font (1.2em) or as a calculated value (calc())

I think we will end up having one --readthedocs-* variable per addon per property if we follow this pattern

What styles do we need that shouldn't be derived from font-size? This would be helpful to enumerate. The majority of styles seem like be positioning and spacing, both mostly proportional to font-size.

Even if there are many other variables required, I still think adding more variables is a good pattern. These variables don't need to map directly to CSS styles directly even.

CSS variables are a benefit because they avoid many of the downsides to JS and HTML customization. More control of CSS styles could render further customization needless even. But also important: a worst case failure of CSS customization is just improper display. JS and HTML customization can throw exceptions if we introduce changes that break user customization.

I'd propose to revert the idea of these --readthedocs-* variables and give us full control

How do we replace user customization for this PR then, what are users expected to do to override our magic?

So far I don't agree with removal, for the points above.

think that using --readthedocs-* is getting pretty complicated to allow us improving the look and feel of the addons while also letting users to modify them.

Agreed, I still think this is completely possible here too. Good defaults are helpful, but we really shouldn't be solely responsible for customization at every tool either. Retaining easy customization points shares this load and doesn't cut out theme maintainers.

humitos · 2025-01-07T14:24:28Z

However, it really seems like we should be able to support both, where we can set a default, and the user can override it?

Yes, we should be able to support both. However, my proposal is to start with good defaults (this PR) and add support for --readthedocs-* variables later due to the complexity I found to support both at this point ¹. The current support of --readthedocs-* is half baked and it's not working in a reliable way, so I'm not worried about removing it for now to allow having better defaults.

With that, we can continue discussing how to support these CSS variables in a better way that works for all the cases, while we give a better UX to our users in the meanwhile.

That said, I agree with the points that Anthony raised in the previous comment, but I'm trying to be more practical now while we debate and learn how to implement it in the near future.

maybe is not super hard but I don't have the knowledge to make it work yet. It will require researching and learning from my side at least. ↩

humitos · 2025-01-08T09:08:28Z

With the latest changes on this PR, this is how the flyout looks by default on different doctools:

My proposal here is to merge it and open a different issue to explore/research/implement the support for CSS variables together with this approach.

ericholscher · 2025-01-08T18:10:36Z

Next steps:

@agjohnson to implement his suggestion of Doctool setting top-level CSS variables
We're 💯 to ship this PR after that.
Document and make official support for CSS variables
Work on internal docs around when and how to use CSS variables when building implementation

agjohnson · 2025-01-08T20:53:21Z

This PR is what I was describing above, for the most part:

Show example of setting attributes and variables at parent DOM #484

It reuses the documentation tool/theme attribute approach instead. But these rules are applied at the parent DOM and allow for users to control these values still.

I would not set line-height specifically. It should be a derived, relative value as should all of the spacing and position values.

I didn't test this further with all of the different tools/themes, I'm not sure how you're testing these. But the underlying pattern for variable use is the most important part here.

humitos · 2025-01-09T10:02:03Z

I'm not sure how you're testing these.

Build all the versions I want to test locally using test-builds
Go to https://readthedocs-addons.readthedocs.io/
Click the slider to make all the links point to my local instance
Click all the links and take a look at the addon

This moves the inner CSS rules from inside the shadow DOM to the parent DOM. This allows users to still set a `--readthedocs-font-size` and similar variables.

humitos · 2025-01-09T10:25:50Z

This looks great to me! It's almost perfect!

humitos · 2025-01-09T10:30:19Z

With this implementation, we can now use a CSS more specific selector to re-define these variables. I understand this is exactly what @agjohnson was suggested and wanted me to use now 😄

Example with a small GIF:

by default the :root selector has no preference over the pre-defined values that Read the Docs defines on html
changing it to readthedocs-flyout makes those --readthedocs- variables to take effect 🎉

We don't need to tell the users to perform extra steps on these documentation tools because addons is going to do this by default now: readthedocs/addons#473

We don't need to tell the users to perform extra steps on these documentation tools because addons is going to do this by default now: readthedocs/addons#473  --- :books: Documentation previews :books: - User's documentation (`docs`): https://docs--11897.org.readthedocs.build/en/11897/   - Developer's documentation (`dev`): https://dev--11897.org.readthedocs.build/en/11897/

ericholscher · 2025-01-09T17:03:30Z

by default the :root selector has no preference over the pre-defined values that Read the Docs defines on html

I thought we wanted folks to be able to define the :root selectors?

ericholscher · 2025-01-09T17:04:30Z

src/flyout.css

+  /* These variables are used more than once, use a local variable so we can set
+   * a default in this addon */


Very useful docstring 💯

ericholscher · 2025-01-09T17:05:45Z

src/flyout.js

@@ -31,9 +37,12 @@ export class FlyoutElement extends LitElement {
    super();

    this.config = null;
+    this.classes = {};


Suggested change

this.classes = {};

Seems this is still an issue?

agjohnson · 2025-01-09T18:22:42Z

by default the :root selector has no preference over the pre-defined values that Read the Docs defines on html

I thought we wanted folks to be able to define the :root selectors?

Because we add rules as :root[data-...=""] -- specificity 0 1 1 -- the specificity of user selectors will need to exceed this or need to target a child element. The following selectors can override our tool detection CSS rules:

html > body/html > * targets a child element of html/:root
readthedocs-flyout targets a deep child element of html/:root
:root:not(.a) is an example that has higher specificity (0 2 0)

ericholscher · 2025-01-09T20:22:38Z

by default the :root selector has no preference over the pre-defined values that Read the Docs defines on html

I thought we wanted folks to be able to define the :root selectors?

Because we add rules as :root[data-...=""] -- specificity 0 1 1 -- the specificity of user selectors will need to exceed this or need to target a child element. The following selectors can override our tool detection CSS rules:

html > body/html > * targets a child element of html/:root
readthedocs-flyout targets a deep child element of html/:root
:root:not(.a) is an example that has higher specificity (0 2 0)

This seems like a great thing to add to the docs 💯

ericholscher · 2025-01-09T20:24:59Z

Added here: readthedocs/readthedocs.org@a371da0

agjohnson · 2025-01-09T21:28:55Z

Actually, it's not needed to target :root. Using @layer we can bump down our defaults in precedence below user contributed selectors, allowing users to just target :root. I'm playing around with whether this is useful to drop the --addons prefix variables too

Edit: it could be, I put some notes in #488

CSS: cleaner pattern for variable use #488

agjohnson · 2025-01-09T22:15:34Z

Updated again at #487

More variable fixes #487

Add styles based on the documentation tool

00f72e0

Use our heuristic to detect the documentation tool/theme and add specific `--readthedocs-*` CSS variables based on that for known tools/themes. Reference: readthedocs/readthedocs.org#11849 (comment)

humitos requested a review from a team as a code owner December 16, 2024 10:46

humitos requested a review from agjohnson December 16, 2024 10:46

agjohnson reviewed Dec 16, 2024

View reviewed changes

src/flyout.js Outdated Show resolved Hide resolved

humitos mentioned this pull request Dec 17, 2024

Add mdbook docs page readthedocs/readthedocs.org#11849

Merged

Use a reactive property to add specific classes

24d7869

agjohnson reviewed Dec 17, 2024

View reviewed changes

src/flyout.js Outdated Show resolved Hide resolved

Use tool=sphinx tool-theme=furo to add CSS rules

f3477b7

humitos added 5 commits December 18, 2024 16:20

Remove unused code

053d931

Update furo font size

8c337ea

Update MkDocs Material font size

9d08961

Useful for Jupyter Book and others

12057bf

Style for Antora

28bb43c

humitos added a commit that referenced this pull request Dec 18, 2024

EthicalAd: specific placement for Antora

300dec5

Based on #473

humitos mentioned this pull request Dec 18, 2024

EthicalAd: specific placement for Antora and mdBook #475

Open

humitos added 2 commits December 18, 2024 17:05

Update snapshots to match tool= and tool-theme= attrs

434f187

Better comment

718b52a

humitos requested review from agjohnson and ericholscher December 18, 2024 16:06

ericholscher reviewed Dec 18, 2024

View reviewed changes

humitos mentioned this pull request Jan 8, 2025

Add Addons customization docs readthedocs/readthedocs.org#11888

Open

humitos added 2 commits January 8, 2025 09:55

Rename attribute with a data- prefix

531c7e2

Adjust style a little more

7f099cc

agjohnson and others added 2 commits January 9, 2025 11:08

Show example of setting attributes and variables at parent DOM (#484)

d6e86c6

This moves the inner CSS rules from inside the shadow DOM to the parent DOM. This allows users to still set a `--readthedocs-font-size` and similar variables.

Small tweaks to font sizes

1446007

humitos mentioned this pull request Jan 9, 2025

Docs: remove CSS variables override for font-size readthedocs/readthedocs.org#11897

Merged

Fix some tests

ed87f06

humitos requested a review from ericholscher January 9, 2025 10:49

Handle error when checking mdBook

4d2a219

ericholscher approved these changes Jan 9, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add styles based on the documentation tool #473

Add styles based on the documentation tool #473

humitos commented Dec 16, 2024

agjohnson left a comment

humitos commented Dec 17, 2024

humitos commented Dec 17, 2024

agjohnson commented Dec 17, 2024

humitos commented Dec 18, 2024

humitos commented Dec 18, 2024

ericholscher left a comment

ericholscher Dec 18, 2024

ericholscher Jan 9, 2025

agjohnson commented Dec 18, 2024

humitos commented Dec 19, 2024 •

edited

Loading

ericholscher commented Dec 19, 2024

agjohnson commented Dec 19, 2024

humitos commented Jan 7, 2025

humitos commented Jan 8, 2025

ericholscher commented Jan 8, 2025

agjohnson commented Jan 8, 2025

humitos commented Jan 9, 2025

humitos commented Jan 9, 2025

humitos commented Jan 9, 2025

ericholscher commented Jan 9, 2025

ericholscher Jan 9, 2025

ericholscher Jan 9, 2025

agjohnson commented Jan 9, 2025

ericholscher commented Jan 9, 2025

ericholscher commented Jan 9, 2025

agjohnson commented Jan 9, 2025 •

edited

Loading

agjohnson commented Jan 9, 2025 •

edited

Loading

		/* These variables are used more than once, use a local variable so we can set
		* a default in this addon */

Add styles based on the documentation tool #473

Are you sure you want to change the base?

Add styles based on the documentation tool #473

Conversation

humitos commented Dec 16, 2024

agjohnson left a comment

Choose a reason for hiding this comment

humitos commented Dec 17, 2024

humitos commented Dec 17, 2024

agjohnson commented Dec 17, 2024

humitos commented Dec 18, 2024

humitos commented Dec 18, 2024

ericholscher left a comment

Choose a reason for hiding this comment

ericholscher Dec 18, 2024

Choose a reason for hiding this comment

ericholscher Jan 9, 2025

Choose a reason for hiding this comment

agjohnson commented Dec 18, 2024

humitos commented Dec 19, 2024 • edited Loading

ericholscher commented Dec 19, 2024

agjohnson commented Dec 19, 2024

humitos commented Jan 7, 2025

Footnotes

humitos commented Jan 8, 2025

ericholscher commented Jan 8, 2025

agjohnson commented Jan 8, 2025

humitos commented Jan 9, 2025

humitos commented Jan 9, 2025

humitos commented Jan 9, 2025

ericholscher commented Jan 9, 2025

ericholscher Jan 9, 2025

Choose a reason for hiding this comment

ericholscher Jan 9, 2025

Choose a reason for hiding this comment

agjohnson commented Jan 9, 2025

ericholscher commented Jan 9, 2025

ericholscher commented Jan 9, 2025

agjohnson commented Jan 9, 2025 • edited Loading

agjohnson commented Jan 9, 2025 • edited Loading

humitos commented Dec 19, 2024 •

edited

Loading

agjohnson commented Jan 9, 2025 •

edited

Loading

agjohnson commented Jan 9, 2025 •

edited

Loading