brainx-sphinx-header 0.1.0__tar.gz

brainx_sphinx_header-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: brainx-sphinx-header
+Version: 0.1.0
+Summary: Sphinx extension that injects the canonical BrainX brand header into any docs site, fetched live from brainx.chaobrain.com.
+Author: BrainX Developers
+License: Apache-2.0
+Project-URL: Homepage, https://brainx.chaobrain.com/
+Project-URL: Source, https://github.com/chaobrain/brainx.chaobrain.com/tree/main/sphinx-ext
+Keywords: sphinx,extension,brainx,documentation,header
+Classifier: Framework :: Sphinx :: Extension
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation :: Sphinx
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: sphinx>=4
+
+# brainx-sphinx-header
+
+Sphinx extension that injects the canonical [BrainX](https://brainx.chaobrain.com/) brand header into any docs site, fetched live from the landing site so every package's docs stays in visual sync.
+
+## Install
+
+```bash
+pip install brainx-sphinx-header
+# or, before publishing:
+pip install "git+https://github.com/chaobrain/brainx.chaobrain.com.git#subdirectory=sphinx-ext"
+```
+
+## Use
+
+In your `docs/conf.py`:
+
+```python
+extensions = [
+    # ...
+    "brainx_sphinx_header",
+]
+```
+
+That's it. On the next build, the BrainX header is fetched from `https://brainx.chaobrain.com/shared-header`, cached at `<docs>/_brand/`, and emitted as `_static/css/brainx-header.css` + `_static/js/brainx-header.js`.
+
+## Configuration (optional)
+
+All settings have sensible defaults. Override in `conf.py` only if you need to.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `brainx_header_url` | `"https://brainx.chaobrain.com/shared-header"` | Where to fetch the canonical header |
+| `brainx_header_ttl` | `3600` | Cache TTL in seconds |
+| `brainx_header_offline` | `False` | Use cache only, never fetch |
+| `brainx_header_local` | `None` | Path to a local shared-header dir for live preview |
+
+Each setting also honors an environment variable (`BRAINX_HEADER_URL`, `BRAINX_HEADER_TTL`, `BRAINX_HEADER_OFFLINE=1`, `BRAINX_HEADER_LOCAL`) which takes precedence — handy for CI.
+
+## What it does
+
+- Fetches `header.html` and `header.css` from the BrainX landing site (with TTL cache + stale fallback).
+- Emits them as Sphinx static assets and registers them via `add_css_file` / `add_js_file`.
+- Appends CSS overrides that hide `sphinx_book_theme` / `pydata_sphinx_theme` native top bars (`header.bd-header`, `.bd-header-article`, `.header-article-items.header-article__inner`).
+- Wires the BrainX header's burger and theme button to the theme's hidden originals (`.primary-toggle`, `.theme-switch-button`) so sidebar toggle and theme cycling keep working — no template overrides needed.
+
+## Local development
+
+To preview a header change against your local landing-site build before pushing:
+
+```bash
+BRAINX_HEADER_LOCAL=/path/to/brainx.chaobrain.com/dist/shared-header sphinx-build -b html docs docs/_build/html
+```
+
+## Supported themes
+
+`sphinx_book_theme`, `pydata_sphinx_theme` (the `bd-*` selector family). Other themes will still render the BrainX header but without button delegation; their native header is unaffected.

brainx_sphinx_header-0.1.0/README.md

@@ -0,0 +1,56 @@
+# brainx-sphinx-header
+
+Sphinx extension that injects the canonical [BrainX](https://brainx.chaobrain.com/) brand header into any docs site, fetched live from the landing site so every package's docs stays in visual sync.
+
+## Install
+
+```bash
+pip install brainx-sphinx-header
+# or, before publishing:
+pip install "git+https://github.com/chaobrain/brainx.chaobrain.com.git#subdirectory=sphinx-ext"
+```
+
+## Use
+
+In your `docs/conf.py`:
+
+```python
+extensions = [
+    # ...
+    "brainx_sphinx_header",
+]
+```
+
+That's it. On the next build, the BrainX header is fetched from `https://brainx.chaobrain.com/shared-header`, cached at `<docs>/_brand/`, and emitted as `_static/css/brainx-header.css` + `_static/js/brainx-header.js`.
+
+## Configuration (optional)
+
+All settings have sensible defaults. Override in `conf.py` only if you need to.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `brainx_header_url` | `"https://brainx.chaobrain.com/shared-header"` | Where to fetch the canonical header |
+| `brainx_header_ttl` | `3600` | Cache TTL in seconds |
+| `brainx_header_offline` | `False` | Use cache only, never fetch |
+| `brainx_header_local` | `None` | Path to a local shared-header dir for live preview |
+
+Each setting also honors an environment variable (`BRAINX_HEADER_URL`, `BRAINX_HEADER_TTL`, `BRAINX_HEADER_OFFLINE=1`, `BRAINX_HEADER_LOCAL`) which takes precedence — handy for CI.
+
+## What it does
+
+- Fetches `header.html` and `header.css` from the BrainX landing site (with TTL cache + stale fallback).
+- Emits them as Sphinx static assets and registers them via `add_css_file` / `add_js_file`.
+- Appends CSS overrides that hide `sphinx_book_theme` / `pydata_sphinx_theme` native top bars (`header.bd-header`, `.bd-header-article`, `.header-article-items.header-article__inner`).
+- Wires the BrainX header's burger and theme button to the theme's hidden originals (`.primary-toggle`, `.theme-switch-button`) so sidebar toggle and theme cycling keep working — no template overrides needed.
+
+## Local development
+
+To preview a header change against your local landing-site build before pushing:
+
+```bash
+BRAINX_HEADER_LOCAL=/path/to/brainx.chaobrain.com/dist/shared-header sphinx-build -b html docs docs/_build/html
+```
+
+## Supported themes
+
+`sphinx_book_theme`, `pydata_sphinx_theme` (the `bd-*` selector family). Other themes will still render the BrainX header but without button delegation; their native header is unaffected.

brainx_sphinx_header-0.1.0/brainx_sphinx_header/__init__.py

@@ -0,0 +1,238 @@
+"""Inject the canonical BrainX brand header into a Sphinx docs site.
+
+The header is fetched live from https://brainx.chaobrain.com/shared-header so
+every package's docs stay in sync with the landing site without copy-paste.
+
+Usage in conf.py
+----------------
+
+    extensions = [
+        ...,
+        "brainx_sphinx_header",
+    ]
+
+Optional configuration (all have sensible defaults):
+
+    brainx_header_url     = "https://brainx.chaobrain.com/shared-header"
+    brainx_header_ttl     = 3600        # cache TTL in seconds
+    brainx_header_offline = False       # use cache only, never fetch
+    brainx_header_local   = None        # str path to a local shared-header dir
+                                        # (e.g. ".../brainx.chaobrain.com/dist/shared-header")
+                                        # for live-preview against an unpushed change
+
+Environment variable overrides (handy in CI):
+
+    BRAINX_HEADER_URL, BRAINX_HEADER_TTL, BRAINX_HEADER_OFFLINE=1, BRAINX_HEADER_LOCAL
+
+What this extension does
+------------------------
+
+1. On ``builder-inited``, fetches header.html + header.css from the BrainX
+   landing site (with TTL cache at ``<confdir>/_brand/``).
+2. Writes them to ``_static/css/brainx-header.css`` and
+   ``_static/js/brainx-header.js`` (the JS embeds the HTML and prepends it to
+   ``<body>`` on DOM ready).
+3. Registers both files via ``add_css_file`` / ``add_js_file``.
+4. The CSS appends overrides that hide ``sphinx_book_theme`` /
+   ``pydata_sphinx_theme`` top bars (``header.bd-header``,
+   ``.bd-header-article``, ``.header-article-items.header-article__inner``) so
+   the BrainX header is the only one visible.
+5. The JS rewires the BrainX header's burger and theme-toggle buttons to the
+   theme's hidden originals (``.primary-toggle`` and ``.theme-switch-button``)
+   via capture-phase ``stopImmediatePropagation``, so sidebar toggle and
+   theme-cycle keep working without touching theme templates.
+
+Supported themes: ``sphinx_book_theme``, ``pydata_sphinx_theme`` (the
+``bd-*`` family). Other themes will still show the BrainX header but won't get
+button delegation; functionality of the theme's own header is unaffected.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from urllib.request import Request, urlopen
+
+from sphinx.application import Sphinx
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE    = "https://brainx.chaobrain.com/shared-header"
+DEFAULT_TTL     = 3600
+ARTIFACT_CSS    = "css/brainx-header.css"
+ARTIFACT_JS     = "js/brainx-header.js"
+CACHE_DIR_NAME  = "_brand"
+
+
+# ---------------------------------------------------------------------------
+# fetch / cache
+# ---------------------------------------------------------------------------
+
+def _fetch(url: str, timeout: int = 10) -> str:
+    req = Request(url, headers={"User-Agent": "brainx-sphinx-header"})
+    with urlopen(req, timeout=timeout) as r:
+        return r.read().decode("utf-8")
+
+
+_ASSETS = ("header.html", "header.css", "header.js")
+
+
+def _read_local(local_dir: Path) -> dict:
+    return {name: (local_dir / name).read_text(encoding="utf-8") for name in _ASSETS}
+
+
+def _load_with_cache(base_url: str, cache_dir: Path, ttl: int, offline: bool) -> dict:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    paths = {name: cache_dir / name for name in _ASSETS}
+    meta_path = cache_dir / "meta.json"
+
+    fresh = False
+    if meta_path.exists() and all(p.exists() for p in paths.values()):
+        try:
+            meta = json.loads(meta_path.read_text())
+            fresh = (time.time() - meta.get("ts", 0)) < ttl
+        except Exception:
+            fresh = False
+
+    if not fresh and not offline:
+        try:
+            fetched = {name: _fetch(f"{base_url}/{name}") for name in _ASSETS}
+            for name, content in fetched.items():
+                paths[name].write_text(content, encoding="utf-8")
+            meta_path.write_text(json.dumps({"ts": time.time(), "src": base_url}))
+            return fetched
+        except Exception as e:
+            if not all(p.exists() for p in paths.values()):
+                raise RuntimeError(
+                    f"[brainx-sphinx-header] fetch failed for {base_url} "
+                    f"and no complete cache exists: {e}"
+                ) from e
+            print(f"[brainx-sphinx-header] fetch failed ({e}); using stale cache at {cache_dir}")
+
+    if not all(p.exists() for p in paths.values()):
+        raise RuntimeError(
+            f"[brainx-sphinx-header] offline=True but cache at {cache_dir} is incomplete. "
+            f"Run once online first."
+        )
+    return {name: paths[name].read_text(encoding="utf-8") for name in _ASSETS}
+
+
+# ---------------------------------------------------------------------------
+# artifact emission (CSS + JS)
+# ---------------------------------------------------------------------------
+
+_THEME_OVERRIDES = """
+
+/* --- brainx-sphinx-header docs-site overrides --- */
+/* Hide pydata_sphinx_theme / sphinx_book_theme native top bars. The
+   BrainX header replaces them visually; their functional buttons remain
+   in the DOM (display: none) so the JS below can still click them. */
+header.bd-header,
+.bd-header-article,
+.header-article-items.header-article__inner {
+  display: none !important;
+}
+
+body {
+  padding-top: 0 !important;
+}
+"""
+
+
+def _build_js(html_payload: str, behavior_js: str, source_label: str) -> str:
+    """Return the bundle the docs site loads.
+
+    Bundle = injection preamble + canonical header.js. The preamble prepends
+    the markup to <body> on DOM ready (Astro doesn't need this — it SSRs the
+    markup). All actual behavior (theme, burger, sphinx delegation) lives in
+    `behavior_js`, fetched verbatim from shared-header/header.js so every host
+    converges on the same logic.
+    """
+    payload = json.dumps(html_payload)
+    preamble = f"""// Auto-generated by brainx-sphinx-header from {source_label}
+(function () {{
+  var HTML = {payload};
+  function inject() {{
+    if (document.querySelector('[data-bx-header]')) return;
+    var holder = document.createElement('div');
+    holder.innerHTML = HTML;
+    var node = holder.firstElementChild;
+    if (node) document.body.insertBefore(node, document.body.firstChild);
+  }}
+  if (document.readyState === 'loading') {{
+    document.addEventListener('DOMContentLoaded', inject);
+  }} else {{
+    inject();
+  }}
+}})();
+"""
+    return preamble + "\n/* --- canonical header.js (shared-header) --- */\n" + behavior_js
+
+
+# ---------------------------------------------------------------------------
+# Sphinx hooks
+# ---------------------------------------------------------------------------
+
+def _resolve_config(app: Sphinx) -> dict:
+    cfg = app.config
+    return {
+        "url":     os.environ.get("BRAINX_HEADER_URL",     cfg.brainx_header_url).rstrip("/"),
+        "ttl":     int(os.environ.get("BRAINX_HEADER_TTL", cfg.brainx_header_ttl)),
+        "offline": (os.environ.get("BRAINX_HEADER_OFFLINE") == "1") or bool(cfg.brainx_header_offline),
+        "local":   os.environ.get("BRAINX_HEADER_LOCAL",   cfg.brainx_header_local),
+    }
+
+
+def _on_builder_inited(app: Sphinx) -> None:
+    cfg     = _resolve_config(app)
+    confdir = Path(app.confdir)
+
+    static_dirs = list(getattr(app.config, "html_static_path", []) or [])
+    if not static_dirs:
+        static_dirs = ["_static"]
+        app.config.html_static_path = static_dirs
+    primary_static = confdir / static_dirs[0]
+
+    css_out = primary_static / ARTIFACT_CSS
+    js_out  = primary_static / ARTIFACT_JS
+    css_out.parent.mkdir(parents=True, exist_ok=True)
+    js_out.parent.mkdir(parents=True,  exist_ok=True)
+
+    if cfg["local"]:
+        assets = _read_local(Path(cfg["local"]))
+        source_label = f"local:{cfg['local']}"
+        print(f"[brainx-sphinx-header] using local source: {cfg['local']}")
+    else:
+        assets = _load_with_cache(
+            cfg["url"],
+            confdir / CACHE_DIR_NAME,
+            cfg["ttl"],
+            cfg["offline"],
+        )
+        source_label = cfg["url"]
+        print(f"[brainx-sphinx-header] source={cfg['url']} offline={cfg['offline']} ttl={cfg['ttl']}")
+
+    css_out.write_text(assets["header.css"] + _THEME_OVERRIDES, encoding="utf-8")
+    js_out.write_text(
+        _build_js(assets["header.html"], assets["header.js"], source_label),
+        encoding="utf-8",
+    )
+
+
+def setup(app: Sphinx) -> dict:
+    app.add_config_value("brainx_header_url",     DEFAULT_BASE, "html")
+    app.add_config_value("brainx_header_ttl",     DEFAULT_TTL,  "html")
+    app.add_config_value("brainx_header_offline", False,        "html")
+    app.add_config_value("brainx_header_local",   None,         "html")
+
+    app.connect("builder-inited", _on_builder_inited)
+    app.add_css_file(ARTIFACT_CSS)
+    app.add_js_file(ARTIFACT_JS)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe":  True,
+        "parallel_write_safe": True,
+    }

brainx_sphinx_header-0.1.0/brainx_sphinx_header.egg-info/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: brainx-sphinx-header
+Version: 0.1.0
+Summary: Sphinx extension that injects the canonical BrainX brand header into any docs site, fetched live from brainx.chaobrain.com.
+Author: BrainX Developers
+License: Apache-2.0
+Project-URL: Homepage, https://brainx.chaobrain.com/
+Project-URL: Source, https://github.com/chaobrain/brainx.chaobrain.com/tree/main/sphinx-ext
+Keywords: sphinx,extension,brainx,documentation,header
+Classifier: Framework :: Sphinx :: Extension
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation :: Sphinx
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: sphinx>=4
+
+# brainx-sphinx-header
+
+Sphinx extension that injects the canonical [BrainX](https://brainx.chaobrain.com/) brand header into any docs site, fetched live from the landing site so every package's docs stays in visual sync.
+
+## Install
+
+```bash
+pip install brainx-sphinx-header
+# or, before publishing:
+pip install "git+https://github.com/chaobrain/brainx.chaobrain.com.git#subdirectory=sphinx-ext"
+```
+
+## Use
+
+In your `docs/conf.py`:
+
+```python
+extensions = [
+    # ...
+    "brainx_sphinx_header",
+]
+```
+
+That's it. On the next build, the BrainX header is fetched from `https://brainx.chaobrain.com/shared-header`, cached at `<docs>/_brand/`, and emitted as `_static/css/brainx-header.css` + `_static/js/brainx-header.js`.
+
+## Configuration (optional)
+
+All settings have sensible defaults. Override in `conf.py` only if you need to.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `brainx_header_url` | `"https://brainx.chaobrain.com/shared-header"` | Where to fetch the canonical header |
+| `brainx_header_ttl` | `3600` | Cache TTL in seconds |
+| `brainx_header_offline` | `False` | Use cache only, never fetch |
+| `brainx_header_local` | `None` | Path to a local shared-header dir for live preview |
+
+Each setting also honors an environment variable (`BRAINX_HEADER_URL`, `BRAINX_HEADER_TTL`, `BRAINX_HEADER_OFFLINE=1`, `BRAINX_HEADER_LOCAL`) which takes precedence — handy for CI.
+
+## What it does
+
+- Fetches `header.html` and `header.css` from the BrainX landing site (with TTL cache + stale fallback).
+- Emits them as Sphinx static assets and registers them via `add_css_file` / `add_js_file`.
+- Appends CSS overrides that hide `sphinx_book_theme` / `pydata_sphinx_theme` native top bars (`header.bd-header`, `.bd-header-article`, `.header-article-items.header-article__inner`).
+- Wires the BrainX header's burger and theme button to the theme's hidden originals (`.primary-toggle`, `.theme-switch-button`) so sidebar toggle and theme cycling keep working — no template overrides needed.
+
+## Local development
+
+To preview a header change against your local landing-site build before pushing:
+
+```bash
+BRAINX_HEADER_LOCAL=/path/to/brainx.chaobrain.com/dist/shared-header sphinx-build -b html docs docs/_build/html
+```
+
+## Supported themes
+
+`sphinx_book_theme`, `pydata_sphinx_theme` (the `bd-*` selector family). Other themes will still render the BrainX header but without button delegation; their native header is unaffected.

brainx_sphinx_header-0.1.0/brainx_sphinx_header.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+brainx_sphinx_header/__init__.py
+brainx_sphinx_header.egg-info/PKG-INFO
+brainx_sphinx_header.egg-info/SOURCES.txt
+brainx_sphinx_header.egg-info/dependency_links.txt
+brainx_sphinx_header.egg-info/requires.txt
+brainx_sphinx_header.egg-info/top_level.txt

brainx_sphinx_header-0.1.0/brainx_sphinx_header.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

brainx_sphinx_header-0.1.0/brainx_sphinx_header.egg-info/requires.txt

@@ -0,0 +1 @@
+sphinx>=4

brainx_sphinx_header-0.1.0/brainx_sphinx_header.egg-info/top_level.txt

@@ -0,0 +1 @@
+brainx_sphinx_header

brainx_sphinx_header-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brainx-sphinx-header"
+version = "0.1.0"
+description = "Sphinx extension that injects the canonical BrainX brand header into any docs site, fetched live from brainx.chaobrain.com."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "BrainX Developers" }]
+keywords = ["sphinx", "extension", "brainx", "documentation", "header"]
+classifiers = [
+  "Framework :: Sphinx :: Extension",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Documentation :: Sphinx",
+]
+dependencies = ["sphinx>=4"]
+
+[project.urls]
+Homepage   = "https://brainx.chaobrain.com/"
+Source     = "https://github.com/chaobrain/brainx.chaobrain.com/tree/main/sphinx-ext"
+
+[tool.setuptools.packages.find]
+include = ["brainx_sphinx_header*"]

brainx_sphinx_header-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+