brainx-sphinx-header 0.1.0

Sphinx extension that injects the canonical BrainX brand header into any docs site, fetched live from brainx.chaobrain.com.

brainx-sphinx-header

Sphinx extension that injects the canonical BrainX brand header into any docs site, fetched live from the landing site so every package's docs stays in visual sync.

Install

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:

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:

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.