PK |=X(0 0 furo/__init__.py"""A clean customisable Sphinx documentation theme."""
__version__ = "2024.01.29"
import hashlib
import logging
import os
from functools import lru_cache
from pathlib import Path
from typing import Any, Dict, Iterator, List, Optional, cast
import sphinx.application
from docutils import nodes
from pygments.formatters import HtmlFormatter
from pygments.style import Style
from pygments.token import Text
from sphinx.builders.dirhtml import DirectoryHTMLBuilder
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.environment.adapters.toctree import TocTree
from sphinx.errors import ConfigError
from sphinx.highlighting import PygmentsBridge
from sphinx.transforms.post_transforms import SphinxPostTransform
from .navigation import get_navigation_tree
THEME_PATH = (Path(__file__).parent / "theme" / "furo").resolve()
logger = logging.getLogger(__name__)
# GLOBAL STATE
_KNOWN_STYLES_IN_USE: Dict[str, Optional[Style]] = {
"light": None,
"dark": None,
}
class WrapTableAndMathInAContainerTransform(SphinxPostTransform):
"""A Sphinx post-transform that wraps `table` and `div.math` in a container `div`.
This makes it possible to handle these overflowing the content-width, which is
necessary in a responsive theme.
"""
formats = ("html",)
default_priority = 500
def run(self, **kwargs: Any) -> None:
"""Perform the post-transform on `self.document`."""
get_nodes = (
self.document.findall # docutils 0.18+
if hasattr(self.document, "findall")
else self.document.traverse # docutils <= 0.17.x
)
for node in list(get_nodes(nodes.table)):
new_node = nodes.container(classes=["table-wrapper"])
new_node.update_all_atts(node)
node.parent.replace(node, new_node)
new_node.append(node)
for node in list(get_nodes(nodes.math_block)):
new_node = nodes.container(classes=["math-wrapper"])
new_node.update_all_atts(node)
node.parent.replace(node, new_node)
new_node.append(node)
def has_not_enough_items_to_show_toc(
builder: StandaloneHTMLBuilder, docname: str
) -> bool:
"""Check if the toc has one or fewer items."""
assert builder.env
toctree = TocTree(builder.env).get_toc_for(docname, builder)
try:
self_toctree = toctree[0][1] # type: ignore[index]
except IndexError:
val = True
else:
# There's only the page's own toctree in there.
val = len(self_toctree) == 1 and self_toctree[0].tagname == "toctree"
return val
def get_pygments_style_colors(
style: Style, *, fallbacks: Dict[str, str]
) -> Dict[str, str]:
"""Get background/foreground colors for given pygments style."""
background = style.background_color # type: ignore[attr-defined]
text_colors = style.style_for_token(Text) # type: ignore[attr-defined]
foreground = text_colors["color"]
if not background:
background = fallbacks["background"]
if not foreground:
foreground = fallbacks["foreground"]
else:
foreground = f"#{foreground}"
return {"background": background, "foreground": foreground}
@lru_cache(maxsize=2)
def get_colors_for_codeblocks(
highlighter: PygmentsBridge, *, fg: str, bg: str
) -> Dict[str, str]:
"""Get background/foreground colors for given pygments style."""
return get_pygments_style_colors(
highlighter.formatter_args["style"],
fallbacks={
"foreground": fg,
"background": bg,
},
)
def _compute_navigation_tree(context: Dict[str, Any]) -> str:
# The navigation tree, generated from the sphinx-provided ToC tree.
if "toctree" in context:
toctree = context["toctree"]
toctree_html = toctree(
collapse=False,
titles_only=True,
maxdepth=-1,
includehidden=True,
)
else:
toctree_html = ""
return get_navigation_tree(toctree_html)
def _compute_hide_toc(
context: Dict[str, Any],
*,
builder: StandaloneHTMLBuilder,
docname: str,
) -> bool:
# Should the table of contents be hidden?
file_meta = context.get("meta", None) or {}
if "hide-toc" in file_meta:
return True
elif "toc" not in context:
return True
elif not context["toc"]:
return True
return has_not_enough_items_to_show_toc(builder, docname)
@lru_cache(maxsize=None)
def _asset_hash(path: str) -> str:
"""Append a `?digest=` to an url based on the file content."""
full_path = THEME_PATH / "static" / path
digest = hashlib.sha1(full_path.read_bytes()).hexdigest()
return f"_static/{path}?digest={digest}"
def _add_asset_hashes(static: List[str], add_digest_to: List[str]) -> None:
if sphinx.version_info >= (7, 1):
# https://github.com/sphinx-doc/sphinx/pull/11415 added the relevant
# functionality to Sphinx, so we don't need to do anything.
return
for asset in add_digest_to:
try:
index = static.index("_static/" + asset)
except ValueError:
raise ConfigError(
"Furo is trying to add a digest to an asset that is not in the "
f"static files: {asset}. Please check conf.py for overrides of "
"theme-provide assets such as `html_style`."
)
# Make this idempotent
if "?digest=" in static[index].filename: # type: ignore[attr-defined]
continue
static[index].filename = _asset_hash(asset) # type: ignore[attr-defined]
def _fix_canonical_url(
app: sphinx.application.Sphinx, pagename: str, context: Dict[str, Any]
) -> None:
"""Fix the canonical URL when using the dirhtml builder.
Sphinx builds a canonical URL if ``html_baseurl`` config is set. However,
it builds a URL ending with ".html" when using the dirhtml builder, which is
incorrect. Detect this and generate the correct URL for each page.
"""
if (
not app.config.html_baseurl
or not isinstance(app.builder, DirectoryHTMLBuilder)
or not context["pageurl"]
or not context["pageurl"].endswith(".html")
):
return
target = app.builder.get_target_uri(pagename)
context["pageurl"] = app.config.html_baseurl + target
def _html_page_context(
app: sphinx.application.Sphinx,
pagename: str,
templatename: str,
context: Dict[str, Any],
doctree: Any,
) -> None:
if "css_files" in context:
_add_asset_hashes(
context["css_files"],
["styles/furo.css", "styles/furo-extensions.css"],
)
if "scripts" in context:
_add_asset_hashes(
context["scripts"],
["scripts/furo.js"],
)
_fix_canonical_url(app, pagename, context)
# Basic constants
context["furo_version"] = __version__
# Values computed from page-level context.
context["furo_navigation_tree"] = _compute_navigation_tree(context)
context["furo_hide_toc"] = _compute_hide_toc(
context, builder=cast(StandaloneHTMLBuilder, app.builder), docname=pagename
)
assert _KNOWN_STYLES_IN_USE["light"]
assert _KNOWN_STYLES_IN_USE["dark"]
# Inject information about styles
context["furo_pygments"] = {
"light": get_pygments_style_colors(
_KNOWN_STYLES_IN_USE["light"],
fallbacks=dict(
foreground="black",
background="white",
),
),
"dark": get_pygments_style_colors(
_KNOWN_STYLES_IN_USE["dark"],
fallbacks=dict(
foreground="white",
background="black",
),
),
}
def _builder_inited(app: sphinx.application.Sphinx) -> None:
if "furo" in app.config.extensions:
raise ConfigError(
"Did you list 'furo' in the `extensions` in conf.py? "
"If so, please remove it. Furo does not work with non-HTML builders "
"and specifying it as an `html_theme` is sufficient."
)
looks_like_html_builder = isinstance(app.builder, StandaloneHTMLBuilder) or (
app.builder.name in {"html", "dirhtml"}
)
if not looks_like_html_builder:
raise ConfigError(
"Furo is being used as an extension in a non-HTML build. "
"This should not happen."
)
# Our JS file needs to be loaded as soon as possible.
app.add_js_file("scripts/furo.js", priority=200)
# 500 is the default priority for extensions, we want this after this.
app.add_css_file("styles/furo-extensions.css", priority=600)
builder = app.builder
assert (
builder.highlighter is not None # type: ignore[attr-defined]
), "there should be a default style known to Sphinx"
assert (
builder.dark_highlighter is None # type: ignore[attr-defined]
), "this shouldn't be a dark style known to Sphinx"
update_known_styles_state(app)
def _update_default(key: str, *, new_default: Any) -> None:
app.config.values[key] = (new_default, *app.config.values[key][1:])
# Change the default permalinks icon
_update_default("html_permalinks_icon", new_default="#")
def update_known_styles_state(app: sphinx.application.Sphinx) -> None:
"""Update a global store of known styles of this application."""
global _KNOWN_STYLES_IN_USE
_KNOWN_STYLES_IN_USE = {
"light": _get_light_style(app),
"dark": _get_dark_style(app),
}
def _get_light_style(app: sphinx.application.Sphinx) -> Style:
# fmt: off
# For https://github.com/psf/black/issues/3869
return (
app # type: ignore[no-any-return]
.builder
.highlighter # type: ignore[attr-defined]
.formatter_args["style"]
)
# fmt: on
def _get_dark_style(app: sphinx.application.Sphinx) -> Style:
dark_style = app.config.pygments_dark_style
return cast(Style, PygmentsBridge("html", dark_style).formatter_args["style"])
def _get_styles(formatter: "HtmlFormatter[str]", *, prefix: str) -> Iterator[str]:
"""Get styles out of a formatter, where everything has the correct prefix."""
for line in formatter.get_linenos_style_defs(): # type: ignore[no-untyped-call]
yield f"{prefix} {line}"
yield from formatter.get_background_style_defs(prefix)
yield from formatter.get_token_style_defs(prefix)
def get_pygments_stylesheet() -> str:
"""Generate the theme-specific pygments.css.
There is no way to tell Sphinx how the theme handles dark mode; at this time.
"""
light_formatter = PygmentsBridge.html_formatter(style=_KNOWN_STYLES_IN_USE["light"])
dark_formatter = PygmentsBridge.html_formatter(style=_KNOWN_STYLES_IN_USE["dark"])
lines: List[str] = []
lines.extend(_get_styles(light_formatter, prefix=".highlight"))
lines.append("@media not print {")
dark_prefix = 'body[data-theme="dark"] .highlight'
lines.extend(_get_styles(dark_formatter, prefix=dark_prefix))
not_light_prefix = 'body:not([data-theme="light"]) .highlight'
lines.append("@media (prefers-color-scheme: dark) {")
lines.extend(_get_styles(dark_formatter, prefix=not_light_prefix))
lines.append("}")
lines.append("}")
return "\n".join(lines)
# Yup, we overwrite the default pygments.css file, because it can't possibly respect
# the needs of this theme.
def _overwrite_pygments_css(
app: sphinx.application.Sphinx,
exception: Optional[Exception],
) -> None:
if exception is not None:
return
assert app.builder
with open(
os.path.join(app.builder.outdir, "_static", "pygments.css"),
"w",
encoding="utf-8",
) as f:
f.write(get_pygments_stylesheet())
def setup(app: sphinx.application.Sphinx) -> Dict[str, Any]:
"""Entry point for sphinx theming."""
app.require_sphinx("6.0")
app.add_config_value(
"pygments_dark_style", default="native", rebuild="env", types=[str]
)
app.add_html_theme("furo", str(THEME_PATH))
app.add_post_transform(WrapTableAndMathInAContainerTransform)
app.connect("html-page-context", _html_page_context)
app.connect("builder-inited", _builder_inited)
app.connect("build-finished", _overwrite_pygments_css)
return {
"parallel_read_safe": True,
"parallel_write_safe": True,
"version": __version__,
}
PK *W{B6m m furo/_demo_module.py# Copyright (c) 2021 Pradyun Gedam
# SPDX-License-Identifier: MIT
"""This is a demo module included in the docs in order to exercise autodoc."""
from typing import Optional, TextIO, Type, Union
def show_warning(
message: Union[Warning, str],
category: Type[Warning],
filename: str,
lineno: int,
file: Optional[TextIO] = None,
line: Optional[str] = None,
) -> None:
"""Show a warning to the end user.
.. code:: python
warnings.showwarning = show_warning
:param message: What you want to tell the user.
:param category: The type of warning.
:param filename: The file that the warning is for.
:param lineno: The line that the warning is for.
:param file: Where to write the warning.
:param line: line of source code to be included in the warning message
"""
class RandomNumberGenerator:
"""A random number generator."""
def __init__(self, *, seed: int = 4) -> None:
"""Initialize."""
self._seed = 4
@property
def seed(self) -> int:
"""Get seed for random number generation.
.. seealso:: https://xkcd.com/221/
"""
return self._seed
def get_random_integer(self) -> int:
"""Return a random integer."""
return self.seed
def get_random_float(self) -> float:
"""Return a random float."""
return float(self.seed)
PK U/P{ { furo/assets/scripts/furo.jsimport Gumshoe from "./gumshoe-patched.js";
////////////////////////////////////////////////////////////////////////////////
// Scroll Handling
////////////////////////////////////////////////////////////////////////////////
var tocScroll = null;
var header = null;
var lastScrollTop = window.pageYOffset || document.documentElement.scrollTop;
const GO_TO_TOP_OFFSET = 64;
function scrollHandlerForHeader() {
if (Math.floor(header.getBoundingClientRect().top) == 0) {
header.classList.add("scrolled");
} else {
header.classList.remove("scrolled");
}
}
function scrollHandlerForBackToTop(positionY) {
if (positionY < GO_TO_TOP_OFFSET) {
document.documentElement.classList.remove("show-back-to-top");
} else {
if (positionY < lastScrollTop) {
document.documentElement.classList.add("show-back-to-top");
} else if (positionY > lastScrollTop) {
document.documentElement.classList.remove("show-back-to-top");
}
}
lastScrollTop = positionY;
}
function scrollHandlerForTOC(positionY) {
if (tocScroll === null) {
return;
}
// top of page.
if (positionY == 0) {
tocScroll.scrollTo(0, 0);
} else if (
// bottom of page.
Math.ceil(positionY) >=
Math.floor(document.documentElement.scrollHeight - window.innerHeight)
) {
tocScroll.scrollTo(0, tocScroll.scrollHeight);
} else {
// somewhere in the middle.
const current = document.querySelector(".scroll-current");
if (current == null) {
return;
}
// https://github.com/pypa/pip/issues/9159 This breaks scroll behaviours.
// // scroll the currently "active" heading in toc, into view.
// const rect = current.getBoundingClientRect();
// if (0 > rect.top) {
// current.scrollIntoView(true); // the argument is "alignTop"
// } else if (rect.bottom > window.innerHeight) {
// current.scrollIntoView(false);
// }
}
}
function scrollHandler(positionY) {
scrollHandlerForHeader();
scrollHandlerForBackToTop(positionY);
scrollHandlerForTOC(positionY);
}
////////////////////////////////////////////////////////////////////////////////
// Theme Toggle
////////////////////////////////////////////////////////////////////////////////
function setTheme(mode) {
if (mode !== "light" && mode !== "dark" && mode !== "auto") {
console.error(`Got invalid theme mode: ${mode}. Resetting to auto.`);
mode = "auto";
}
document.body.dataset.theme = mode;
localStorage.setItem("theme", mode);
console.log(`Changed to ${mode} mode.`);
}
function cycleThemeOnce() {
const currentTheme = localStorage.getItem("theme") || "auto";
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
if (prefersDark) {
// Auto (dark) -> Light -> Dark
if (currentTheme === "auto") {
setTheme("light");
} else if (currentTheme == "light") {
setTheme("dark");
} else {
setTheme("auto");
}
} else {
// Auto (light) -> Dark -> Light
if (currentTheme === "auto") {
setTheme("dark");
} else if (currentTheme == "dark") {
setTheme("light");
} else {
setTheme("auto");
}
}
}
////////////////////////////////////////////////////////////////////////////////
// Setup
////////////////////////////////////////////////////////////////////////////////
function setupScrollHandler() {
// Taken from https://developer.mozilla.org/en-US/docs/Web/API/Document/scroll_event
let last_known_scroll_position = 0;
let ticking = false;
window.addEventListener("scroll", function (e) {
last_known_scroll_position = window.scrollY;
if (!ticking) {
window.requestAnimationFrame(function () {
scrollHandler(last_known_scroll_position);
ticking = false;
});
ticking = true;
}
});
window.scroll();
}
function setupScrollSpy() {
if (tocScroll === null) {
return;
}
// Scrollspy -- highlight table on contents, based on scroll
new Gumshoe(".toc-tree a", {
reflow: true,
recursive: true,
navClass: "scroll-current",
offset: () => {
let rem = parseFloat(getComputedStyle(document.documentElement).fontSize);
return header.getBoundingClientRect().height + 0.5 * rem + 1;
},
});
}
function setupTheme() {
// Attach event handlers for toggling themes
const buttons = document.getElementsByClassName("theme-toggle");
Array.from(buttons).forEach((btn) => {
btn.addEventListener("click", cycleThemeOnce);
});
}
function setup() {
setupTheme();
setupScrollHandler();
setupScrollSpy();
}
////////////////////////////////////////////////////////////////////////////////
// Main entrypoint
////////////////////////////////////////////////////////////////////////////////
function main() {
document.body.parentNode.classList.remove("no-js");
header = document.querySelector("header");
tocScroll = document.querySelector(".toc-scroll");
setup();
}
document.addEventListener("DOMContentLoaded", main);
PK WK2 2 & furo/assets/scripts/gumshoe-patched.js/*!
* gumshoejs v5.1.2 (patched by @pradyunsg)
* A simple, framework-agnostic scrollspy script.
* (c) 2019 Chris Ferdinandi
* MIT License
* http://github.com/cferdinandi/gumshoe
*/
(function (root, factory) {
if (typeof define === "function" && define.amd) {
define([], function () {
return factory(root);
});
} else if (typeof exports === "object") {
module.exports = factory(root);
} else {
root.Gumshoe = factory(root);
}
})(
typeof global !== "undefined"
? global
: typeof window !== "undefined"
? window
: this,
function (window) {
"use strict";
//
// Defaults
//
var defaults = {
// Active classes
navClass: "active",
contentClass: "active",
// Nested navigation
nested: false,
nestedClass: "active",
// Offset & reflow
offset: 0,
reflow: false,
// Event support
events: true,
};
//
// Methods
//
/**
* Merge two or more objects together.
* @param {Object} objects The objects to merge together
* @returns {Object} Merged values of defaults and options
*/
var extend = function () {
var merged = {};
Array.prototype.forEach.call(arguments, function (obj) {
for (var key in obj) {
if (!obj.hasOwnProperty(key)) return;
merged[key] = obj[key];
}
});
return merged;
};
/**
* Emit a custom event
* @param {String} type The event type
* @param {Node} elem The element to attach the event to
* @param {Object} detail Any details to pass along with the event
*/
var emitEvent = function (type, elem, detail) {
// Make sure events are enabled
if (!detail.settings.events) return;
// Create a new event
var event = new CustomEvent(type, {
bubbles: true,
cancelable: true,
detail: detail,
});
// Dispatch the event
elem.dispatchEvent(event);
};
/**
* Get an element's distance from the top of the Document.
* @param {Node} elem The element
* @return {Number} Distance from the top in pixels
*/
var getOffsetTop = function (elem) {
var location = 0;
if (elem.offsetParent) {
while (elem) {
location += elem.offsetTop;
elem = elem.offsetParent;
}
}
return location >= 0 ? location : 0;
};
/**
* Sort content from first to last in the DOM
* @param {Array} contents The content areas
*/
var sortContents = function (contents) {
if (contents) {
contents.sort(function (item1, item2) {
var offset1 = getOffsetTop(item1.content);
var offset2 = getOffsetTop(item2.content);
if (offset1 < offset2) return -1;
return 1;
});
}
};
/**
* Get the offset to use for calculating position
* @param {Object} settings The settings for this instantiation
* @return {Float} The number of pixels to offset the calculations
*/
var getOffset = function (settings) {
// if the offset is a function run it
if (typeof settings.offset === "function") {
return parseFloat(settings.offset());
}
// Otherwise, return it as-is
return parseFloat(settings.offset);
};
/**
* Get the document element's height
* @private
* @returns {Number}
*/
var getDocumentHeight = function () {
return Math.max(
document.body.scrollHeight,
document.documentElement.scrollHeight,
document.body.offsetHeight,
document.documentElement.offsetHeight,
document.body.clientHeight,
document.documentElement.clientHeight,
);
};
/**
* Determine if an element is in view
* @param {Node} elem The element
* @param {Object} settings The settings for this instantiation
* @param {Boolean} bottom If true, check if element is above bottom of viewport instead
* @return {Boolean} Returns true if element is in the viewport
*/
var isInView = function (elem, settings, bottom) {
var bounds = elem.getBoundingClientRect();
var offset = getOffset(settings);
if (bottom) {
return (
parseInt(bounds.bottom, 10) <
(window.innerHeight || document.documentElement.clientHeight)
);
}
return parseInt(bounds.top, 10) <= offset;
};
/**
* Check if at the bottom of the viewport
* @return {Boolean} If true, page is at the bottom of the viewport
*/
var isAtBottom = function () {
if (
Math.ceil(window.innerHeight + window.pageYOffset) >=
getDocumentHeight()
)
return true;
return false;
};
/**
* Check if the last item should be used (even if not at the top of the page)
* @param {Object} item The last item
* @param {Object} settings The settings for this instantiation
* @return {Boolean} If true, use the last item
*/
var useLastItem = function (item, settings) {
if (isAtBottom() && isInView(item.content, settings, true)) return true;
return false;
};
/**
* Get the active content
* @param {Array} contents The content areas
* @param {Object} settings The settings for this instantiation
* @return {Object} The content area and matching navigation link
*/
var getActive = function (contents, settings) {
var last = contents[contents.length - 1];
if (useLastItem(last, settings)) return last;
for (var i = contents.length - 1; i >= 0; i--) {
if (isInView(contents[i].content, settings)) return contents[i];
}
};
/**
* Deactivate parent navs in a nested navigation
* @param {Node} nav The starting navigation element
* @param {Object} settings The settings for this instantiation
*/
var deactivateNested = function (nav, settings) {
// If nesting isn't activated, bail
if (!settings.nested || !nav.parentNode) return;
// Get the parent navigation
var li = nav.parentNode.closest("li");
if (!li) return;
// Remove the active class
li.classList.remove(settings.nestedClass);
// Apply recursively to any parent navigation elements
deactivateNested(li, settings);
};
/**
* Deactivate a nav and content area
* @param {Object} items The nav item and content to deactivate
* @param {Object} settings The settings for this instantiation
*/
var deactivate = function (items, settings) {
// Make sure there are items to deactivate
if (!items) return;
// Get the parent list item
var li = items.nav.closest("li");
if (!li) return;
// Remove the active class from the nav and content
li.classList.remove(settings.navClass);
items.content.classList.remove(settings.contentClass);
// Deactivate any parent navs in a nested navigation
deactivateNested(li, settings);
// Emit a custom event
emitEvent("gumshoeDeactivate", li, {
link: items.nav,
content: items.content,
settings: settings,
});
};
/**
* Activate parent navs in a nested navigation
* @param {Node} nav The starting navigation element
* @param {Object} settings The settings for this instantiation
*/
var activateNested = function (nav, settings) {
// If nesting isn't activated, bail
if (!settings.nested) return;
// Get the parent navigation
var li = nav.parentNode.closest("li");
if (!li) return;
// Add the active class
li.classList.add(settings.nestedClass);
// Apply recursively to any parent navigation elements
activateNested(li, settings);
};
/**
* Activate a nav and content area
* @param {Object} items The nav item and content to activate
* @param {Object} settings The settings for this instantiation
*/
var activate = function (items, settings) {
// Make sure there are items to activate
if (!items) return;
// Get the parent list item
var li = items.nav.closest("li");
if (!li) return;
// Add the active class to the nav and content
li.classList.add(settings.navClass);
items.content.classList.add(settings.contentClass);
// Activate any parent navs in a nested navigation
activateNested(li, settings);
// Emit a custom event
emitEvent("gumshoeActivate", li, {
link: items.nav,
content: items.content,
settings: settings,
});
};
/**
* Create the Constructor object
* @param {String} selector The selector to use for navigation items
* @param {Object} options User options and settings
*/
var Constructor = function (selector, options) {
//
// Variables
//
var publicAPIs = {};
var navItems, contents, current, timeout, settings;
//
// Methods
//
/**
* Set variables from DOM elements
*/
publicAPIs.setup = function () {
// Get all nav items
navItems = document.querySelectorAll(selector);
// Create contents array
contents = [];
// Loop through each item, get it's matching content, and push to the array
Array.prototype.forEach.call(navItems, function (item) {
// Get the content for the nav item
var content = document.getElementById(
decodeURIComponent(item.hash.substr(1)),
);
if (!content) return;
// Push to the contents array
contents.push({
nav: item,
content: content,
});
});
// Sort contents by the order they appear in the DOM
sortContents(contents);
};
/**
* Detect which content is currently active
*/
publicAPIs.detect = function () {
// Get the active content
var active = getActive(contents, settings);
// if there's no active content, deactivate and bail
if (!active) {
if (current) {
deactivate(current, settings);
current = null;
}
return;
}
// If the active content is the one currently active, do nothing
if (current && active.content === current.content) return;
// Deactivate the current content and activate the new content
deactivate(current, settings);
activate(active, settings);
// Update the currently active content
current = active;
};
/**
* Detect the active content on scroll
* Debounced for performance
*/
var scrollHandler = function (event) {
// If there's a timer, cancel it
if (timeout) {
window.cancelAnimationFrame(timeout);
}
// Setup debounce callback
timeout = window.requestAnimationFrame(publicAPIs.detect);
};
/**
* Update content sorting on resize
* Debounced for performance
*/
var resizeHandler = function (event) {
// If there's a timer, cancel it
if (timeout) {
window.cancelAnimationFrame(timeout);
}
// Setup debounce callback
timeout = window.requestAnimationFrame(function () {
sortContents(contents);
publicAPIs.detect();
});
};
/**
* Destroy the current instantiation
*/
publicAPIs.destroy = function () {
// Undo DOM changes
if (current) {
deactivate(current, settings);
}
// Remove event listeners
window.removeEventListener("scroll", scrollHandler, false);
if (settings.reflow) {
window.removeEventListener("resize", resizeHandler, false);
}
// Reset variables
contents = null;
navItems = null;
current = null;
timeout = null;
settings = null;
};
/**
* Initialize the current instantiation
*/
var init = function () {
// Merge user options into defaults
settings = extend(defaults, options || {});
// Setup variables based on the current DOM
publicAPIs.setup();
// Find the currently active content
publicAPIs.detect();
// Setup event listeners
window.addEventListener("scroll", scrollHandler, false);
if (settings.reflow) {
window.addEventListener("resize", resizeHandler, false);
}
};
//
// Initialize and return the public APIs
//
init();
return publicAPIs;
};
//
// Return the Constructor
//
return Constructor;
},
);
PK NKWi% % ! furo/assets/styles/_scaffold.sass// This file contains the styles for the overall layouting of the documentation
// skeleton, including the responsive changes as well as sidebar toggles.
//
// This is implemented as a mobile-last design, which isn't ideal, but it is
// reasonably good-enough and I got pretty tired by the time I'd finished this
// to move the rules around to fix this. Shouldn't take more than 3-4 hours,
// if you know what you're doing tho.
// HACK: Not all browsers account for the scrollbar width in media queries.
// This results in horizontal scrollbars in the breakpoint where we go
// from displaying everything to hiding the ToC. We accomodate for this by
// adding a bit of padding to the TOC drawer, disabling the horizontal
// scrollbar and allowing the scrollbars to cover the padding.
// https://www.456bereastreet.com/archive/201301/media_query_width_and_vertical_scrollbars/
// HACK: Always having the scrollbar visible, prevents certain browsers from
// causing the content to stutter horizontally between taller-than-viewport and
// not-taller-than-viewport pages.
html
overflow-x: hidden
overflow-y: scroll
scroll-behavior: smooth
.sidebar-scroll, .toc-scroll, article[role=main] *
// Override Firefox scrollbar style
scrollbar-width: thin
scrollbar-color: var(--color-foreground-border) transparent
// Override Chrome scrollbar styles
&::-webkit-scrollbar
width: 0.25rem
height: 0.25rem
&::-webkit-scrollbar-thumb
background-color: var(--color-foreground-border)
border-radius: 0.125rem
//
// Overalls
//
html,
body
height: 100%
color: var(--color-foreground-primary)
background: var(--color-background-primary)
article
color: var(--color-content-foreground)
background: var(--color-content-background)
overflow-wrap: break-word
.page
display: flex
// fill the viewport for pages with little content.
min-height: 100%
.mobile-header
width: 100%
height: var(--header-height)
background-color: var(--color-header-background)
color: var(--color-header-text)
border-bottom: 1px solid var(--color-header-border)
// Looks like sub-script/super-script have this, and we need this to
// be "on top" of those.
z-index: 10
// We don't show the header on large screens.
display: none
// Add shadow when scrolled
&.scrolled
border-bottom: none
box-shadow: 0 0 0.2rem rgba(0, 0, 0, 0.1), 0 0.2rem 0.4rem rgba(0, 0, 0, 0.2)
.header-center
a
color: var(--color-header-text)
text-decoration: none
.main
display: flex
flex: 1
// Sidebar (left) also covers the entire left portion of screen.
.sidebar-drawer
box-sizing: border-box
border-right: 1px solid var(--color-sidebar-background-border)
background: var(--color-sidebar-background)
display: flex
justify-content: flex-end
// These next two lines took me two days to figure out.
width: calc((100% - #{$full-width}) / 2 + #{$sidebar-width})
min-width: $sidebar-width
// Scroll-along sidebars
.sidebar-container,
.toc-drawer
box-sizing: border-box
width: $sidebar-width
.toc-drawer
background: var(--color-toc-background)
// See HACK described on top of this document
padding-right: 1rem
.sidebar-sticky,
.toc-sticky
position: sticky
top: 0
height: min(100%, 100vh)
height: 100vh
display: flex
flex-direction: column
.sidebar-scroll,
.toc-scroll
flex-grow: 1
flex-shrink: 1
overflow: auto
scroll-behavior: smooth
// Central items.
.content
padding: 0 $content-padding
width: $content-width
display: flex
flex-direction: column
justify-content: space-between
.icon
display: inline-block
height: 1rem
width: 1rem
svg
width: 100%
height: 100%
//
// Accommodate announcement banner
//
.announcement
background-color: var(--color-announcement-background)
color: var(--color-announcement-text)
height: var(--header-height)
display: flex
align-items: center
overflow-x: auto
& + .page
min-height: calc(100% - var(--header-height))
.announcement-content
box-sizing: border-box
padding: 0.5rem
min-width: 100%
white-space: nowrap
text-align: center
a
color: var(--color-announcement-text)
text-decoration-color: var(--color-announcement-text)
&:hover
color: var(--color-announcement-text)
text-decoration-color: var(--color-link--hover)
////////////////////////////////////////////////////////////////////////////////
// Toggles for theme
////////////////////////////////////////////////////////////////////////////////
.no-js .theme-toggle-container // don't show theme toggle if there's no JS
display: none
.theme-toggle-container
vertical-align: middle
.theme-toggle
cursor: pointer
border: none
padding: 0
background: transparent
.theme-toggle svg
vertical-align: middle
height: 1rem
width: 1rem
color: var(--color-foreground-primary)
display: none
.theme-toggle-header
float: left
padding: 1rem 0.5rem
////////////////////////////////////////////////////////////////////////////////
// Toggles for elements
////////////////////////////////////////////////////////////////////////////////
.toc-overlay-icon, .nav-overlay-icon
display: none
cursor: pointer
.icon
color: var(--color-foreground-secondary)
height: 1rem
width: 1rem
.toc-header-icon, .nav-overlay-icon
// for when we set display: flex
justify-content: center
align-items: center
.toc-content-icon
height: 1.5rem
width: 1.5rem
.content-icon-container
float: right
display: flex
margin-top: 1.5rem
margin-left: 1rem
margin-bottom: 1rem
gap: 0.5rem
.edit-this-page svg
color: inherit
height: 1rem
width: 1rem
.sidebar-toggle
position: absolute
display: none
//
.sidebar-toggle[name="__toc"]
left: 20px
.sidebar-toggle:checked
left: 40px
//
.overlay
position: fixed
top: 0
width: 0
height: 0
transition: width 0ms, height 0ms, opacity 250ms ease-out
opacity: 0
background-color: rgba(0, 0, 0, 0.54)
.sidebar-overlay
z-index: 20
.toc-overlay
z-index: 40
// Keep things on top and smooth.
.sidebar-drawer
z-index: 30
transition: left 250ms ease-in-out
.toc-drawer
z-index: 50
transition: right 250ms ease-in-out
// Show the Sidebar
#__navigation:checked
& ~ .sidebar-overlay
width: 100%
height: 100%
opacity: 1
& ~ .page
.sidebar-drawer
top: 0
left: 0
// Show the toc sidebar
#__toc:checked
& ~ .toc-overlay
width: 100%
height: 100%
opacity: 1
& ~ .page
.toc-drawer
top: 0
right: 0
////////////////////////////////////////////////////////////////////////////////
// Back to top
////////////////////////////////////////////////////////////////////////////////
.back-to-top
text-decoration: none
display: none
position: fixed
left: 0
top: 1rem
padding: 0.5rem
padding-right: 0.75rem
border-radius: 1rem
font-size: 0.8125rem
background: var(--color-background-primary)
box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), #6b728080 0px 0px 1px 0px
z-index: 10
margin-left: 50%
transform: translateX(-50%)
svg
height: 1rem
width: 1rem
fill: currentColor
display: inline-block
span
margin-left: 0.25rem
.show-back-to-top &
display: flex
align-items: center
////////////////////////////////////////////////////////////////////////////////
// Responsive layouting
////////////////////////////////////////////////////////////////////////////////
// Make things a bit bigger on bigger screens.
@media (min-width: $full-width + $sidebar-width)
html
font-size: 110%
@media (max-width: $full-width)
// Collapse "toc" into the icon.
.toc-content-icon
display: flex
.toc-drawer
position: fixed
height: 100vh
top: 0
right: -$sidebar-width
border-left: 1px solid var(--color-background-muted)
.toc-tree
border-left: none
font-size: var(--toc-font-size--mobile)
// Accomodate for a changed content width.
.sidebar-drawer
width: calc((100% - #{$full-width - $sidebar-width}) / 2 + #{$sidebar-width})
@media (max-width: $full-width - $sidebar-width)
// Collapse "navigation".
.nav-overlay-icon
display: flex
.sidebar-drawer
position: fixed
height: 100vh
width: $sidebar-width
top: 0
left: -$sidebar-width
// Swap which icon is visible.
.toc-header-icon
display: flex
.toc-content-icon, .theme-toggle-content
display: none
.theme-toggle-header
display: block
// Show the header.
.mobile-header
position: sticky
top: 0
display: flex
justify-content: space-between
align-items: center
.header-left,
.header-right
display: flex
height: var(--header-height)
padding: 0 var(--header-padding)
label
height: 100%
width: 100%
user-select: none
.nav-overlay-icon .icon,
.theme-toggle svg
height: 1.25rem
width: 1.25rem
// Add a scroll margin for the content
:target
scroll-margin-top: var(--header-height)
// Show back-to-top below the header
.back-to-top
top: calc(var(--header-height) + 0.5rem)
// Center the page, and accommodate for the header.
.page
flex-direction: column
justify-content: center
.content
margin-left: auto
margin-right: auto
@media (max-width: $content-width + 2* $content-padding)
// Content should respect window limits.
.content
width: 100%
overflow-x: auto
@media (max-width: $content-width)
.content
padding: 0 $content-padding--small
// Don't float sidebars to the right.
article aside.sidebar
float: none
width: 100%
margin: 1rem 0
PK U%v5 5 furo/assets/styles/_shame.sass// Shameful hacks, to work around bugs.
// MyST parser doesn't correctly generate classes, to align table contents.
// https://github.com/executablebooks/MyST-Parser/issues/412
.text-align\:left > p
text-align: left
.text-align\:center > p
text-align: center
.text-align\:right > p
text-align: right
PK U8ZN N # furo/assets/styles/base/_index.sass@import "print"
@import "screen-readers"
@import "theme"
@import "typography"
PK UK{ { # furo/assets/styles/base/_print.sass// This file contains styles for managing print media.
////////////////////////////////////////////////////////////////////////////////
// Hide elements not relevant to print media.
////////////////////////////////////////////////////////////////////////////////
@media print
// Hide icon container.
.content-icon-container
display: none !important
// Hide showing header links if hovering over when printing.
.headerlink
display: none !important
// Hide mobile header.
.mobile-header
display: none !important
// Hide navigation links.
.related-pages
display: none !important
////////////////////////////////////////////////////////////////////////////////
// Tweaks related to decolorization.
////////////////////////////////////////////////////////////////////////////////
@media print
// Apply a border around code which no longer have a color background.
.highlight
border: 0.1pt solid var(--color-foreground-border)
////////////////////////////////////////////////////////////////////////////////
// Avoid page break in some relevant cases.
////////////////////////////////////////////////////////////////////////////////
@media print
ul, ol, dl, a, table, pre, blockquote
page-break-inside: avoid
h1, h2, h3, h4, h5, h6, img, figure, caption
page-break-inside: avoid
page-break-after: avoid
ul, ol, dl
page-break-before: avoid
PK UY|%4, , , furo/assets/styles/base/_screen-readers.sass.visually-hidden
position: absolute !important
width: 1px !important
height: 1px !important
padding: 0 !important
margin: -1px !important
overflow: hidden !important
clip: rect(0,0,0,0) !important
white-space: nowrap !important
border: 0 !important
:-moz-focusring
outline: auto
PK UFoH # furo/assets/styles/base/_theme.sass// This file serves as the "skeleton" of the theming logic.
//
// This contains the bulk of the logic for handling dark mode, color scheme
// toggling and the handling of color-scheme-specific hiding of elements.
body
@include fonts
@include spacing
@include icons
@include admonitions
@include default-admonition(#651fff, "abstract")
@include default-topic(#14B8A6, "pencil")
@include colors
.only-light
display: block !important
html body .only-dark
display: none !important
// Ignore dark-mode hints if print media.
@media not print
// Enable dark-mode, if requested.
body[data-theme="dark"]
@include colors-dark
html & .only-light
display: none !important
.only-dark
display: block !important
// Enable dark mode, unless explicitly told to avoid.
@media (prefers-color-scheme: dark)
body:not([data-theme="light"])
@include colors-dark
html & .only-light
display: none !important
.only-dark
display: block !important
//
// Theme toggle presentation
//
body[data-theme="auto"]
.theme-toggle svg.theme-icon-when-auto
display: block
body[data-theme="dark"]
.theme-toggle svg.theme-icon-when-dark
display: block
body[data-theme="light"]
.theme-toggle svg.theme-icon-when-light
display: block
PK Uhi
( furo/assets/styles/base/_typography.sass// This file contains the styling for making the content throughout the page,
// including fonts, paragraphs, headings and spacing among these elements.
body
font-family: var(--font-stack)
pre,
code,
kbd,
samp
font-family: var(--font-stack--monospace)
// Make fonts look slightly nicer.
body
-webkit-font-smoothing: antialiased
-moz-osx-font-smoothing: grayscale
// Line height from Bootstrap 4.1
article
line-height: 1.5
//
// Headings
//
h1,
h2,
h3,
h4,
h5,
h6
line-height: 1.25
font-weight: bold
border-radius: 0.5rem
margin-top: 0.5rem
margin-bottom: 0.5rem
margin-left: -0.5rem
margin-right: -0.5rem
padding-left: 0.5rem
padding-right: 0.5rem
+ p
margin-top: 0
h1
font-size: 2.5em
margin-top: 1.75rem
margin-bottom: 1rem
h2
font-size: 2em
margin-top: 1.75rem
h3
font-size: 1.5em
h4
font-size: 1.25em
h5
font-size: 1.125em
h6
font-size: 1em
small
opacity: 75%
font-size: 80%
// Paragraph
p
margin-top: 0.5rem
margin-bottom: 0.75rem
// Horizontal rules
hr.docutils
height: 1px
padding: 0
margin: 2rem 0
background-color: var(--color-background-border)
border: 0
.centered
text-align: center
// Links
a
text-decoration: underline
color: var(--color-link)
text-decoration-color: var(--color-link-underline)
&:hover
color: var(--color-link--hover)
text-decoration-color: var(--color-link-underline--hover)
&.muted-link
color: inherit
&:hover
color: var(--color-link)
text-decoration-color: var(--color-link-underline--hover)
PK 3\YVSn˺ * furo/assets/styles/components/_footer.sass// This file contains the styles used for stylizing the footer that's shown
// below the content.
footer
font-size: var(--font-size--small)
display: flex
flex-direction: column
margin-top: 2rem
// Bottom of page information
.bottom-of-page
display: flex
align-items: center
justify-content: space-between
margin-top: 1rem
padding-top: 1rem
padding-bottom: 1rem
color: var(--color-foreground-secondary)
border-top: 1px solid var(--color-background-border)
line-height: 1.5
@media (max-width: $content-width)
text-align: center
flex-direction: column-reverse
gap: 0.25rem
.left-details
font-size: var(--font-size--small)
.right-details
display: flex
flex-direction: column
gap: 0.25rem
text-align: right
.icons
display: flex
justify-content: flex-end
gap: 0.25rem
font-size: 1rem
a
text-decoration: none
svg,
img
font-size: 1.125rem
height: 1em
width: 1em
// Next/Prev page information
.related-pages
a
display: flex
align-items: center
text-decoration: none
&:hover .page-info .title
text-decoration: underline
color: var(--color-link)
text-decoration-color: var(--color-link-underline)
svg.furo-related-icon,
svg.furo-related-icon > use
flex-shrink: 0
color: var(--color-foreground-border)
width: 0.75rem
height: 0.75rem
margin: 0 0.5rem
&.next-page
max-width: 50%
float: right
clear: right
text-align: right
&.prev-page
max-width: 50%
float: left
clear: left
svg
transform: rotate(180deg)
.page-info
display: flex
flex-direction: column
overflow-wrap: anywhere
.next-page &
align-items: flex-end
.context
display: flex
align-items: center
padding-bottom: 0.1rem
color: var(--color-foreground-muted)
font-size: var(--font-size--small)
text-decoration: none
PK Uq`P P ) furo/assets/styles/components/_index.sass@import "footer"
@import "search"
@import "sidebar"
@import "table_of_contents"
PK U9H H * furo/assets/styles/components/_search.sass//
// Search Page Listing
//
ul.search
padding-left: 0
list-style: none
li
padding: 1rem 0
border-bottom: 1px solid var(--color-background-border)
//
// Highlighted by links in search page
//
[role=main] .highlighted
background-color: var(--color-highlighted-background)
color: var(--color-highlighted-text)
PK UZ/ + furo/assets/styles/components/_sidebar.sass// This file contains the styles for the contents of the left sidebar, which
// contains the navigation tree, logo, search etc.
////////////////////////////////////////////////////////////////////////////////
// Brand on top of the scrollable tree.
////////////////////////////////////////////////////////////////////////////////
.sidebar-brand
display: flex
flex-direction: column
flex-shrink: 0
padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)
text-decoration: none
.sidebar-brand-text
color: var(--color-sidebar-brand-text)
overflow-wrap: break-word
margin: var(--sidebar-item-spacing-vertical) 0
font-size: 1.5rem
.sidebar-logo-container
margin: var(--sidebar-item-spacing-vertical) 0
.sidebar-logo
margin: 0 auto
display: block
max-width: 100%
////////////////////////////////////////////////////////////////////////////////
// Search
////////////////////////////////////////////////////////////////////////////////
.sidebar-search-container
display: flex
align-items: center
margin-top: var(--sidebar-search-space-above)
position: relative
background: var(--color-sidebar-search-background)
&:hover,
&:focus-within
background: var(--color-sidebar-search-background--focus)
&::before
content: ""
position: absolute
left: var(--sidebar-item-spacing-horizontal)
width: var(--sidebar-search-icon-size)
height: var(--sidebar-search-icon-size)
background-color: var(--color-sidebar-search-icon)
mask-image: var(--icon-search)
.sidebar-search
box-sizing: border-box
border: none
border-top: 1px solid var(--color-sidebar-search-border)
border-bottom: 1px solid var(--color-sidebar-search-border)
padding-top: var(--sidebar-search-input-spacing-vertical)
padding-bottom: var(--sidebar-search-input-spacing-vertical)
padding-right: var(--sidebar-search-input-spacing-horizontal)
padding-left: calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size))
width: 100%
color: var(--color-sidebar-search-foreground)
background: transparent
z-index: 10
&:focus
outline: none
&::placeholder
font-size: var(--sidebar-search-input-font-size)
//
// Hide Search Matches link
//
#searchbox .highlight-link
padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0
margin: 0
text-align: center
a
color: var(--color-sidebar-search-icon)
font-size: var(--font-size--small--2)
////////////////////////////////////////////////////////////////////////////////
// Structure/Skeleton of the navigation tree (left)
////////////////////////////////////////////////////////////////////////////////
.sidebar-tree
font-size: var(--sidebar-item-font-size)
margin-top: var(--sidebar-tree-space-above)
margin-bottom: var(--sidebar-item-spacing-vertical)
ul
padding: 0
margin-top: 0
margin-bottom: 0
display: flex
flex-direction: column
list-style: none
li
position: relative
margin: 0
> ul
margin-left: var(--sidebar-item-spacing-horizontal)
.icon
color: var(--color-sidebar-link-text)
.reference
box-sizing: border-box
color: var(--color-sidebar-link-text)
// Fill the parent.
display: inline-block
line-height: var(--sidebar-item-line-height)
text-decoration: none
// Don't allow long words to cause wrapping.
overflow-wrap: anywhere
height: 100%
width: 100%
padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)
&:hover
background: var(--color-sidebar-item-background--hover)
// Add a nice little "external-link" arrow here.
&.external::after
content: url('data:image/svg+xml,')
margin: 0 0.25rem
vertical-align: middle
color: var(--color-sidebar-link-text)
// Make the current page reference bold.
.current-page > .reference
font-weight: bold
label
position: absolute
top: 0
right: 0
height: var(--sidebar-item-height)
width: var(--sidebar-expander-width)
cursor: pointer
user-select: none
display: flex
justify-content: center
align-items: center
.caption, :not(.caption) > .caption-text
font-size: var(--sidebar-caption-font-size)
color: var(--color-sidebar-caption-text)
font-weight: bold
text-transform: uppercase
margin: var(--sidebar-caption-space-above) 0 0 0
padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)
// If it has children, add a bit more padding to wrap the content to avoid
// overlapping with the