brainx-sphinx-header 0.4.0

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

brainx-sphinx-header

Sphinx extension that injects the canonical BrainX brand header and footer 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

Use

In your docs/conf.py:

extensions = [
    # ...
    "brainx_sphinx_header",
]

That's it. On the next build, the BrainX header and footer are 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 (plus the matching brainx-footer.{css,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
brainx_inject_base	True	Inject <base href="{html_baseurl}"> into the docs index so the site works at both /<pkg> and /<pkg>/ (no-op if html_baseurl is unset)

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, header.css, header.js, footer.html, footer.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.
• Header: 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.
• Footer: appends below the theme's native footer. No theme overrides — the BrainX footer coexists with the theme footer rather than replacing it. The build year is baked into the markup at extension-emit time.
• Slash-tolerant index: injects <base href="{html_baseurl}"> into the docs index page, so the site renders correctly whether reached via https://host/<pkg> or https://host/<pkg>/. Sub-pages already resolve correctly via their own real paths and are not touched. Pair with an exact-match nginx block (location = /<pkg> { alias .../current/index.html; default_type text/html; }) to actually serve the no-slash URL without a redirect. Disable via brainx_inject_base = False if you want the historical 301-redirect behavior.

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.