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.
