From e376fc3dc8d42af3ed4fe0903ee310996f46bcf0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Mon, 19 Aug 2024 16:14:58 +0200 Subject: [PATCH] doc: extensions: Add Doxygen tooltips to main documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Doxygen tooltips in the main documentation. The tooltips are triggered when hovering over C symbols in the documentation and display a preview of the Doxygen documentation for the symbol. Some shadow DOM magic is needed to style the tooltips correctly, without affecting the rest of the page. (cherry picked from commit bd29c5c410bd983a7655984fd562d4a7296f78a6) Original-Signed-off-by: Benjamin Cabé GitOrigin-RevId: bd29c5c410bd983a7655984fd562d4a7296f78a6 Cr-Build-Id: 8738238973287044049 Cr-Build-Url: https://cr-buildbucket.appspot.com/build/8738238973287044049 Copybot-Job-Name: zephyr-main-copybot-downstream Change-Id: I80ebcb13e72ec95f1c7397643dd331bc1464f9d1 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/third_party/zephyr/+/5827660 Tested-by: ChromeOS Prod (Robot) Reviewed-by: Ting Shen Commit-Queue: Ting Shen Tested-by: Ting Shen --- .../zephyr/doxytooltip/__init__.py | 36 +++++ .../zephyr/doxytooltip/static/doxytooltip.css | 36 +++++ .../zephyr/doxytooltip/static/doxytooltip.js | 133 ++++++++++++++++++ .../doxytooltip/static/tippy/popper.min.js | 8 ++ .../static/tippy/tippy-bundle.umd.min.js | 7 + doc/conf.py | 1 + 6 files changed, 221 insertions(+) create mode 100644 doc/_extensions/zephyr/doxytooltip/__init__.py create mode 100644 doc/_extensions/zephyr/doxytooltip/static/doxytooltip.css create mode 100644 doc/_extensions/zephyr/doxytooltip/static/doxytooltip.js create mode 100644 doc/_extensions/zephyr/doxytooltip/static/tippy/popper.min.js create mode 100644 doc/_extensions/zephyr/doxytooltip/static/tippy/tippy-bundle.umd.min.js diff --git a/doc/_extensions/zephyr/doxytooltip/__init__.py b/doc/_extensions/zephyr/doxytooltip/__init__.py new file mode 100644 index 00000000000..8c768fded27 --- /dev/null +++ b/doc/_extensions/zephyr/doxytooltip/__init__.py @@ -0,0 +1,36 @@ +""" +Doxygen Tooltip Extension +######################### + +Copyright (c) 2024 The Linux Foundation +SPDX-License-Identifier: Apache-2.0 + +A simple Sphinx extension that adds JS and CSS resources to the app +to enable tooltips for C domain links. +""" + +from pathlib import Path + +from typing import Any, Dict + +from sphinx.application import Sphinx +from sphinx.util import logging + +logger = logging.getLogger(__name__) + +RESOURCES_DIR = Path(__file__).parent / "static" + +def setup(app: Sphinx) -> Dict[str, Any]: + app.config.html_static_path.append(RESOURCES_DIR.as_posix()) + + app.add_js_file("tippy/popper.min.js") + app.add_js_file("tippy/tippy-bundle.umd.min.js") + + app.add_js_file("doxytooltip.js") + app.add_css_file("doxytooltip.css") + + return { + "version": "0.1", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/doc/_extensions/zephyr/doxytooltip/static/doxytooltip.css b/doc/_extensions/zephyr/doxytooltip/static/doxytooltip.css new file mode 100644 index 00000000000..39113599083 --- /dev/null +++ b/doc/_extensions/zephyr/doxytooltip/static/doxytooltip.css @@ -0,0 +1,36 @@ +.tippy-box[data-theme~='doxytooltip'] { + /* provide minimal definition of the CSS variables used by Doxygen Awesome so that we have a + look and feel that's consistent with the rest of the documentation without necessarily aiming + for full fidelity */ + --font-family-monospace: SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', Courier, monospace; + --primary-color: var(--navbar-heading-color); + --param-color: var(--code-literal-color); + --border-radius-small: 4px; + --border-radius-medium: 6px; + --border-radius-large: 8px; + + background-color: var(--content-wrap-background-color); + color: var(--body-color); +} + +.tippy-box[data-theme~='doxytooltip'][data-placement^='top']>.tippy-arrow::before { + border-top-color: var(--content-wrap-background-color); +} + +.tippy-box[data-theme~='doxytooltip'][data-placement^='bottom']>.tippy-arrow::before { + border-bottom-color: var(--content-wrap-background-color); +} + +.tippy-box[data-theme~='doxytooltip'][data-placement^='left']>.tippy-arrow::before { + border-left-color: var(--content-wrap-background-color); +} + +.tippy-box[data-theme~='doxytooltip'][data-placement^='right']>.tippy-arrow::before { + border-right-color: var(--content-wrap-background-color); +} + +.tippy-box[data-theme~='doxytooltip'] .tippy-content { + font-size: 0.9em; + max-height: 300px; + overflow-y: scroll; +} diff --git a/doc/_extensions/zephyr/doxytooltip/static/doxytooltip.js b/doc/_extensions/zephyr/doxytooltip/static/doxytooltip.js new file mode 100644 index 00000000000..be2088910c1 --- /dev/null +++ b/doc/_extensions/zephyr/doxytooltip/static/doxytooltip.js @@ -0,0 +1,133 @@ +/** + * Copyright (c) 2024, Benjamin Cabé + * SPDX-License-Identifier: Apache-2.0 + * + * This script adds mouse hover hooks to the current page to display + * Doxygen documentation as tooltips when hovering over a symbol in the + * documentation. + */ + +registerDoxygenTooltip = function () { + const parser = new DOMParser(); + + const tooltip = document.createElement('div'); + tooltip.id = 'doxytooltip'; + document.body.appendChild(tooltip); + + const tooltipShadow = document.createElement('div'); + tooltipShadow.id = 'doxytooltip-shadow'; + tooltip.attachShadow({ mode: 'open' }).appendChild(tooltipShadow); + + /* tippy's JS code automatically adds a