From 00f72e0f7329eb0d51e9bd1b7d5bb31aae745c3e Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 16 Dec 2024 11:44:27 +0100 Subject: [PATCH 01/10] Add styles based on the documentation tool Use our heuristic to detect the documentation tool/theme and add specific `--readthedocs-*` CSS variables based on that for known tools/themes. Reference: https://github.com/readthedocs/readthedocs.org/pull/11849#issuecomment-2540234995 --- src/flyout.js | 21 ++++++++++++++++++++- src/flyout.mkdocs.material.css | 4 ++++ src/flyout.sphinx.furo.css | 4 ++++ 3 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 src/flyout.mkdocs.material.css create mode 100644 src/flyout.sphinx.furo.css diff --git a/src/flyout.js b/src/flyout.js index a10c975..974567e 100644 --- a/src/flyout.js +++ b/src/flyout.js @@ -8,7 +8,15 @@ import { classMap } from "lit/directives/class-map.js"; import { default as objectPath } from "object-path"; import styleSheet from "./flyout.css"; -import { AddonBase, addUtmParameters, getLinkWithFilename } from "./utils"; +import styleMkDocsMaterial from "./flyout.mkdocs.material.css"; +import styleSphinxFuro from "./flyout.sphinx.furo.css"; +import { + AddonBase, + addUtmParameters, + getLinkWithFilename, + docTool, +} from "./utils"; +import { SPHINX, MKDOCS_MATERIAL } from "./constants"; import { EVENT_READTHEDOCS_SEARCH_SHOW, EVENT_READTHEDOCS_FLYOUT_HIDE, @@ -387,6 +395,17 @@ export class FlyoutAddon extends AddonBase { for (const elem of elems) { elem.loadConfig(config); } + + this.addCustomStyle(); + } + + addCustomStyle() { + const doctool = docTool.documentationTool; + if (doctool === MKDOCS_MATERIAL) { + document.adoptedStyleSheets.push(styleMkDocsMaterial); + } else if (doctool == SPHINX && docTool.isSphinxFuroLikeTheme()) { + document.adoptedStyleSheets.push(styleSphinxFuro); + } } } diff --git a/src/flyout.mkdocs.material.css b/src/flyout.mkdocs.material.css new file mode 100644 index 0000000..61c2aa6 --- /dev/null +++ b/src/flyout.mkdocs.material.css @@ -0,0 +1,4 @@ +:root { + /* Reduce Read the Docs' flyout font a little bit */ + --readthedocs-flyout-font-size: 0.7rem; +} diff --git a/src/flyout.sphinx.furo.css b/src/flyout.sphinx.furo.css new file mode 100644 index 0000000..b5d141f --- /dev/null +++ b/src/flyout.sphinx.furo.css @@ -0,0 +1,4 @@ +:root { + /* Reduce Read the Docs' flyout font a little bit */ + --readthedocs-flyout-font-size: 0.75rem; +} From 24d786941d4c0aaefcb328e89e5f8edec6e96c9d Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 17 Dec 2024 11:59:22 +0100 Subject: [PATCH 02/10] Use a reactive property to add specific classes --- src/flyout.css | 9 ++++++++ src/flyout.js | 38 ++++++++++++++++++++-------------- src/flyout.mkdocs.material.css | 4 ---- src/flyout.sphinx.furo.css | 4 ---- 4 files changed, 31 insertions(+), 24 deletions(-) delete mode 100644 src/flyout.mkdocs.material.css delete mode 100644 src/flyout.sphinx.furo.css diff --git a/src/flyout.css b/src/flyout.css index 7d175ae..63c2f35 100644 --- a/src/flyout.css +++ b/src/flyout.css @@ -155,3 +155,12 @@ small a { text-decoration: none; color: var(--readthedocs-flyout-link-color, rgb(42, 128, 185)); } + +/* Specific styles */ +.mkdocs-material { + --addons-flyout-font-size: 0.6rem; +} + +.sphinx-furo { + --addons-flyout-font-size: 0.75rem; +} diff --git a/src/flyout.js b/src/flyout.js index 974567e..ada1e66 100644 --- a/src/flyout.js +++ b/src/flyout.js @@ -8,8 +8,6 @@ import { classMap } from "lit/directives/class-map.js"; import { default as objectPath } from "object-path"; import styleSheet from "./flyout.css"; -import styleMkDocsMaterial from "./flyout.mkdocs.material.css"; -import styleSphinxFuro from "./flyout.sphinx.furo.css"; import { AddonBase, addUtmParameters, @@ -28,6 +26,7 @@ export class FlyoutElement extends LitElement { static properties = { config: { state: true }, + classes: { state: true, type: Object }, opened: { type: Boolean }, floating: { type: Boolean }, position: { type: String }, @@ -39,6 +38,7 @@ export class FlyoutElement extends LitElement { super(); this.config = null; + this.classes = {}; this.opened = false; this.floating = true; this.position = "bottom-right"; @@ -75,6 +75,22 @@ export class FlyoutElement extends LitElement { } }; + firstUpdated() { + console.log("Flyout first update."); + const doctool = docTool.documentationTool; + if (doctool === MKDOCS_MATERIAL) { + console.log("MkDocs Material custom style."); + this.classes["mkdocs-material"] = true; + } else if (doctool == SPHINX && docTool.isSphinxFuroLikeTheme()) { + console.log("Sphinx Furo custom style."); + this.classes["sphinx-furo"] = true; + } + + // FIXME: I don't understand why this doesn't trigger an update + // automatically, since `this.classes` is a reactive property. + this.requestUpdate(); + } + renderHeader() { library.add(faCodeBranch); library.add(faLanguage); @@ -318,11 +334,12 @@ export class FlyoutElement extends LitElement { return nothing; } - const classes = { floating: this.floating, container: true }; - classes[this.position] = true; + Object.assign(this.classes, { floating: this.floating, container: true }); + this.classes[this.position] = true; + console.log(this.classes); return html` -
+
${this.renderHeader()}
${this.renderLanguages()} ${this.renderVersions()} @@ -395,17 +412,6 @@ export class FlyoutAddon extends AddonBase { for (const elem of elems) { elem.loadConfig(config); } - - this.addCustomStyle(); - } - - addCustomStyle() { - const doctool = docTool.documentationTool; - if (doctool === MKDOCS_MATERIAL) { - document.adoptedStyleSheets.push(styleMkDocsMaterial); - } else if (doctool == SPHINX && docTool.isSphinxFuroLikeTheme()) { - document.adoptedStyleSheets.push(styleSphinxFuro); - } } } diff --git a/src/flyout.mkdocs.material.css b/src/flyout.mkdocs.material.css deleted file mode 100644 index 61c2aa6..0000000 --- a/src/flyout.mkdocs.material.css +++ /dev/null @@ -1,4 +0,0 @@ -:root { - /* Reduce Read the Docs' flyout font a little bit */ - --readthedocs-flyout-font-size: 0.7rem; -} diff --git a/src/flyout.sphinx.furo.css b/src/flyout.sphinx.furo.css deleted file mode 100644 index b5d141f..0000000 --- a/src/flyout.sphinx.furo.css +++ /dev/null @@ -1,4 +0,0 @@ -:root { - /* Reduce Read the Docs' flyout font a little bit */ - --readthedocs-flyout-font-size: 0.75rem; -} From f3477b7cb461e1bc2b14bbb6163be1b2cb608b2b Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 18 Dec 2024 16:16:06 +0100 Subject: [PATCH 03/10] Use `tool=sphinx` `tool-theme=furo` to add CSS rules --- src/constants.js | 6 ++++++ src/flyout.css | 10 +++++++--- src/flyout.js | 13 +++++++------ src/utils.js | 42 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 62 insertions(+), 9 deletions(-) diff --git a/src/constants.js b/src/constants.js index 463b61f..5c8b4b0 100644 --- a/src/constants.js +++ b/src/constants.js @@ -8,4 +8,10 @@ export const ASCIIDOCTOR = "asciidoctor"; export const JEKYLL = "jekyll"; export const DOCSIFY = "docsify"; export const ANTORA = "antora"; +export const MDBOOK = "mdbook"; export const FALLBACK_DOCTOOL = "fallback"; + +// Known documentation tools themes +export const SPHINX_ALABASTER = "alabaster"; +export const SPHINX_FURO = "furo"; +export const SPHINX_READTHEDOCS = "readthedocs"; diff --git a/src/flyout.css b/src/flyout.css index 63c2f35..48f7370 100644 --- a/src/flyout.css +++ b/src/flyout.css @@ -157,10 +157,14 @@ small a { } /* Specific styles */ -.mkdocs-material { +div[tool="mkdocs-material"] { --addons-flyout-font-size: 0.6rem; } -.sphinx-furo { - --addons-flyout-font-size: 0.75rem; +div[tool="mdbook"] { + --addons-flyout-font-size: 1.3rem; +} + +div[tool="sphinx"][tool-theme="furo"] { + --addons-flyout-font-size: 0.8rem; } diff --git a/src/flyout.js b/src/flyout.js index ada1e66..0a88886 100644 --- a/src/flyout.js +++ b/src/flyout.js @@ -26,7 +26,6 @@ export class FlyoutElement extends LitElement { static properties = { config: { state: true }, - classes: { state: true, type: Object }, opened: { type: Boolean }, floating: { type: Boolean }, position: { type: String }, @@ -42,6 +41,8 @@ export class FlyoutElement extends LitElement { this.opened = false; this.floating = true; this.position = "bottom-right"; + this.classes = { floating: this.floating, container: true }; + this.classes[this.position] = true; this.readthedocsLogo = READTHEDOCS_LOGO; } @@ -334,12 +335,12 @@ export class FlyoutElement extends LitElement { return nothing; } - Object.assign(this.classes, { floating: this.floating, container: true }); - this.classes[this.position] = true; - console.log(this.classes); - return html` -
+
${this.renderHeader()}
${this.renderLanguages()} ${this.renderVersions()} diff --git a/src/utils.js b/src/utils.js index e144e05..b31f11f 100644 --- a/src/utils.js +++ b/src/utils.js @@ -2,6 +2,10 @@ import { ajv } from "./data-validation"; import { default as objectPath } from "object-path"; import { SPHINX, + SPHINX_FURO, + SPHINX_ALABASTER, + SPHINX_READTHEDOCS, + MDBOOK, MKDOCS, MKDOCS_MATERIAL, DOCUSAURUS, @@ -297,6 +301,7 @@ export class DocumentationTool { constructor() { this.documentationTool = this.getDocumentationTool(); + this.documentationTheme = this.getDocumentationTheme(); console.debug(`Documentation tool detected: ${this.documentationTool}`); } @@ -411,10 +416,47 @@ export class DocumentationTool { return DOCSIFY; } + if (this.isMdBook()) { + return MDBOOK; + } + console.debug("We were not able to detect the documentation tool."); return null; } + getDocumentationTheme() { + const documentationTool = + this.documentationTool || this.getDocumentationTool(); + + if (documentationTool === SPHINX) { + if (this.isSphinxAlabasterLikeTheme()) { + return SPHINX_ALABASTER; + } else if (this.isSphinxReadTheDocsLikeTheme()) { + return SPHINX_READTHEDOCS; + } else if (this.isSphinxFuroLikeTheme()) { + return SPHINX_FURO; + } + } + + // TODO: add the other known themes + return null; + } + + isMdBook() { + // + // + // + // ... + if ( + document.head.firstChild.nextSibling.textContent.includes( + "Book generated using mdBook", + ) + ) { + return true; + } + return false; + } + isDocsify() { if (document.querySelectorAll("head > link[href*=docsify]").length) { return true; From 053d9319150d59c321427f21df77d9b69d159177 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 18 Dec 2024 16:20:46 +0100 Subject: [PATCH 04/10] Remove unused code --- src/flyout.js | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/src/flyout.js b/src/flyout.js index 0a88886..f044aac 100644 --- a/src/flyout.js +++ b/src/flyout.js @@ -76,22 +76,6 @@ export class FlyoutElement extends LitElement { } }; - firstUpdated() { - console.log("Flyout first update."); - const doctool = docTool.documentationTool; - if (doctool === MKDOCS_MATERIAL) { - console.log("MkDocs Material custom style."); - this.classes["mkdocs-material"] = true; - } else if (doctool == SPHINX && docTool.isSphinxFuroLikeTheme()) { - console.log("Sphinx Furo custom style."); - this.classes["sphinx-furo"] = true; - } - - // FIXME: I don't understand why this doesn't trigger an update - // automatically, since `this.classes` is a reactive property. - this.requestUpdate(); - } - renderHeader() { library.add(faCodeBranch); library.add(faLanguage); From 8c337eaa40863923a32a710d04820fafa3f2ec45 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 18 Dec 2024 16:21:45 +0100 Subject: [PATCH 05/10] Update furo font size --- src/flyout.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/flyout.css b/src/flyout.css index 48f7370..87c3f36 100644 --- a/src/flyout.css +++ b/src/flyout.css @@ -166,5 +166,5 @@ div[tool="mdbook"] { } div[tool="sphinx"][tool-theme="furo"] { - --addons-flyout-font-size: 0.8rem; + --addons-flyout-font-size: 0.75rem; } From 9d08961eb4bdd7c00226c5296c20472c8b008fa2 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 18 Dec 2024 16:24:32 +0100 Subject: [PATCH 06/10] Update MkDocs Material font size --- src/flyout.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/flyout.css b/src/flyout.css index 87c3f36..a1a84e6 100644 --- a/src/flyout.css +++ b/src/flyout.css @@ -158,7 +158,7 @@ small a { /* Specific styles */ div[tool="mkdocs-material"] { - --addons-flyout-font-size: 0.6rem; + --addons-flyout-font-size: 0.65rem; } div[tool="mdbook"] { From 12057bfda1cb83ef3ce94879789f55da958a7547 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 18 Dec 2024 16:30:26 +0100 Subject: [PATCH 07/10] Useful for Jupyter Book and others --- src/flyout.css | 1 + 1 file changed, 1 insertion(+) diff --git a/src/flyout.css b/src/flyout.css index a1a84e6..e6508cd 100644 --- a/src/flyout.css +++ b/src/flyout.css @@ -7,6 +7,7 @@ height: auto; max-height: calc(100% - 100px); overflow-y: auto; + line-height: 1rem; } .container.bottom-right { From 28bb43cc920186d18d0eb9635f914bc29f005520 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 18 Dec 2024 16:47:13 +0100 Subject: [PATCH 08/10] Style for Antora --- src/constants.js | 1 + src/flyout.css | 11 +++++++++++ src/utils.js | 32 +++++++++++++++++++++++++++++++- 3 files changed, 43 insertions(+), 1 deletion(-) diff --git a/src/constants.js b/src/constants.js index 5c8b4b0..2658958 100644 --- a/src/constants.js +++ b/src/constants.js @@ -15,3 +15,4 @@ export const FALLBACK_DOCTOOL = "fallback"; export const SPHINX_ALABASTER = "alabaster"; export const SPHINX_FURO = "furo"; export const SPHINX_READTHEDOCS = "readthedocs"; +export const SPHINX_IMMATERIAL = "immaterial"; diff --git a/src/flyout.css b/src/flyout.css index e6508cd..a2a22d5 100644 --- a/src/flyout.css +++ b/src/flyout.css @@ -160,6 +160,12 @@ small a { /* Specific styles */ div[tool="mkdocs-material"] { --addons-flyout-font-size: 0.65rem; + line-height: 0.8rem; +} + +div[tool="antora"] { + --addons-flyout-font-size: 0.7rem; + line-height: 0.9rem; } div[tool="mdbook"] { @@ -169,3 +175,8 @@ div[tool="mdbook"] { div[tool="sphinx"][tool-theme="furo"] { --addons-flyout-font-size: 0.75rem; } + +div[tool="sphinx"][tool-theme="immaterial"] { + --addons-flyout-font-size: 0.65rem; + line-height: 0.8rem; +} diff --git a/src/utils.js b/src/utils.js index b31f11f..27ec259 100644 --- a/src/utils.js +++ b/src/utils.js @@ -5,6 +5,7 @@ import { SPHINX_FURO, SPHINX_ALABASTER, SPHINX_READTHEDOCS, + SPHINX_IMMATERIAL, MDBOOK, MKDOCS, MKDOCS_MATERIAL, @@ -420,6 +421,10 @@ export class DocumentationTool { return MDBOOK; } + if (this.isAntora()) { + return ANTORA; + } + console.debug("We were not able to detect the documentation tool."); return null; } @@ -435,6 +440,8 @@ export class DocumentationTool { return SPHINX_READTHEDOCS; } else if (this.isSphinxFuroLikeTheme()) { return SPHINX_FURO; + } else if (this.isSphinxImmaterialLikeTheme()) { + return SPHINX_IMMATERIAL; } } @@ -442,6 +449,16 @@ export class DocumentationTool { return null; } + isAntora() { + if ( + document.querySelectorAll('meta[name="generator"][content^="Antora"]') + .length + ) { + return true; + } + return false; + } + isMdBook() { // // @@ -469,7 +486,8 @@ export class DocumentationTool { this.isSphinxAlabasterLikeTheme() || this.isSphinxReadTheDocsLikeTheme() || this.isSphinxFuroLikeTheme() || - this.isSphinxBookThemeLikeTheme() + this.isSphinxBookThemeLikeTheme() || + this.isSphinxImmaterialLikeTheme() ); } @@ -573,6 +591,18 @@ export class DocumentationTool { return false; } + isSphinxImmaterialLikeTheme() { + if ( + document.querySelectorAll( + 'link[href^="_static/sphinx_immaterial_theme"]', + 'a[href="https://github.com/jbms/sphinx-immaterial/"][rel="noopener"]', + ).length + ) { + return true; + } + return false; + } + isMaterialMkDocsTheme() { if ( document.querySelectorAll( From 434f1876562da1f70b63d555c5817a5a22da9968 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Wed, 18 Dec 2024 17:05:44 +0100 Subject: [PATCH 09/10] Update snapshots to match `tool=` and `tool-theme=` attrs --- tests/__snapshots__/flyout.test.snap.js | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/tests/__snapshots__/flyout.test.snap.js b/tests/__snapshots__/flyout.test.snap.js index 827779a..af61cd0 100644 --- a/tests/__snapshots__/flyout.test.snap.js +++ b/tests/__snapshots__/flyout.test.snap.js @@ -2,7 +2,11 @@ export const snapshots = {}; snapshots["Flyout addon snapshot flyout completely"] = -`
+`
Read the Docs +`
Read the Docs Date: Wed, 18 Dec 2024 17:06:28 +0100 Subject: [PATCH 10/10] Better comment --- src/flyout.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/flyout.css b/src/flyout.css index a2a22d5..c9e3dcc 100644 --- a/src/flyout.css +++ b/src/flyout.css @@ -157,7 +157,7 @@ small a { color: var(--readthedocs-flyout-link-color, rgb(42, 128, 185)); } -/* Specific styles */ +/* Specific styles based on documentation tools and themes */ div[tool="mkdocs-material"] { --addons-flyout-font-size: 0.65rem; line-height: 0.8rem;