add collapsing api docs

Author: psifertex

api-docs/source/_static/css/other.css

@@ -14,3 +14,47 @@
 .colon {
     display: none !important;
 }
+
+/* Desktop only; mobile keeps the theme's slide-in nav and top-bar hamburger. */
+@media screen and (min-width: 769px) {
+	/* Toggled by js/sidebar_toggle.js; reuses the theme's off-screen nav. */
+	#bn-sidebar-toggle {
+		position: fixed;
+		top: 12px;
+		left: 312px;
+		z-index: 10000;
+		width: 36px;
+		height: 36px;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		border: none;
+		background: #fff;
+		color: #111;
+		font-size: 18px;
+		cursor: pointer;
+		opacity: 0.85;
+	}
+
+	#bn-sidebar-toggle:hover {
+		opacity: 1;
+	}
+
+	html.bn-sidebar-collapsed #bn-sidebar-toggle {
+		left: 12px;
+	}
+
+	html.bn-sidebar-collapsed .wy-nav-side {
+		left: -300px;
+	}
+
+	html.bn-sidebar-collapsed .wy-nav-content-wrap {
+		margin-left: 0;
+	}
+}
+
+@media screen and (max-width: 768px) {
+	#bn-sidebar-toggle {
+		display: none;
+	}
+}

api-docs/source/_static/js/sidebar_toggle.js

@@ -0,0 +1,68 @@
+// Collapsible navigation sidebar for the API docs (issue #7867).
+(() => {
+	const KEY = "bn_api_sidebar_collapsed";
+	const CLS = "bn-sidebar-collapsed";
+	const root = document.documentElement;
+	// Collapse is desktop only; on mobile the theme's hamburger owns the nav.
+	const desktop = window.matchMedia("(min-width: 769px)");
+
+	const save = (v) => { try { localStorage.setItem(KEY, v); } catch (e) {} };
+	const load = () => { try { return localStorage.getItem(KEY); } catch (e) { return null; } };
+
+	let collapsed = load() === "1";
+
+	// Apply saved state before first paint to avoid a layout flash.
+	root.classList.toggle(CLS, collapsed);
+
+	const sync = () => {
+		const btn = document.getElementById("bn-sidebar-toggle");
+		const nav = document.querySelector(".wy-nav-side");
+		// Only hide the nav from AT when it is actually offscreen.
+		const hidden = collapsed && desktop.matches;
+		if (btn) {
+			btn.setAttribute("aria-pressed", collapsed ? "true" : "false");
+			btn.title = collapsed ? "Show navigation" : "Hide navigation";
+		}
+		if (nav) {
+			if (hidden) {
+				nav.setAttribute("aria-hidden", "true");
+				nav.setAttribute("inert", "");
+			} else {
+				nav.removeAttribute("aria-hidden");
+				nav.removeAttribute("inert");
+			}
+		}
+	};
+
+	const setCollapsed = (v) => {
+		collapsed = v;
+		root.classList.toggle(CLS, collapsed);
+		save(collapsed ? "1" : "0");
+		sync();
+	};
+
+	const addButton = () => {
+		const nav = document.querySelector(".wy-nav-side");
+		if (nav && !nav.id) nav.id = "bn-nav-side";
+
+		const btn = document.createElement("button");
+		btn.id = "bn-sidebar-toggle";
+		btn.type = "button";
+		btn.setAttribute("aria-label", "Toggle navigation");
+		if (nav) btn.setAttribute("aria-controls", nav.id);
+		btn.textContent = "☰";
+		btn.addEventListener("click", () => setCollapsed(!collapsed));
+		document.body.appendChild(btn);
+		sync();
+	};
+
+	// addListener fallback for older Safari/WebKit without addEventListener.
+	if (desktop.addEventListener) desktop.addEventListener("change", sync);
+	else desktop.addListener(sync);
+
+	if (document.readyState === "loading") {
+		document.addEventListener("DOMContentLoaded", addButton);
+	} else {
+		addButton();
+	}
+})();

api-docs/source/conf.py

@@ -197,6 +197,7 @@ def write_summary_table(output, header, members):
 
 def setup(app):
 	app.add_css_file('css/other.css')
+	app.add_js_file('js/sidebar_toggle.js')
 	app.is_parallel_allowed('write')
 
 def generaterst():