For Sphinx & Read the Docs

Ask AI for your Sphinx docs

Q: How long does the install take?

Install sphinx-biel and add three lines to conf.py. Indexing time depends on the size and number of versions.

Drop in an Ask AI assistant via the sphinx-biel extension. Three lines in conf.py. Source-cited answers, multilingual out of the box, autodoc-aware citations, and a Content Gaps view that shows what your docs don't cover. Works with sphinx-rtd-theme, furo, pydata-sphinx-theme, and Read the Docs.

Add Biel to Sphinx See the install code

14-day free trialNo credit card required

acme.readthedocs.io/en/stable/api.html

Docs » API Reference » acme.routes

acme.routes.configure_rate_limit

acme.routes.configure_rate_limit(route, requests, per='minute', burst=None)

Configure per-route rate limiting. Each endpoint has its own bucket, scoped to the route path; authenticated and anonymous traffic are metered separately.

Parameters

route (str) — Route path, e.g. /v1/checkout.
requests (int) — Maximum requests per window.
burst (int, optional) — Transient surge cap above the steady-state limit.

Used by documentation and developer-experience teams

Install

Three ways to ship Biel on Sphinx

A floating Ask AI assistant via sphinx-biel, a page-search field with an Ask AI handoff in a layout.html override, or a hosted MCP endpoint Claude and Cursor can query directly.

Full installation guide

Add the assistant via sphinx-biel

The standard install. The sphinx-biel extension wires the Ask AI button into every built page. Three lines in conf.py: install, register, set the project ID. Layout, position, and theme are tunable through biel_* config values, with no _templates/ overrides needed.

→Floating Ask AI button on every built page
→Works with sphinx-rtd-theme, furo, pydata-sphinx-theme
→Index published Read the Docs pages
→Indexes RST, MyST, and autodoc output

conf.py

# 1. pip install sphinx-biel
# 2. Register and configure in conf.py.

extensions = [
    # ... your existing extensions
    'sphinx_biel',
]

biel_project = '<YOUR_PROJECT_ID>'
biel_header_title = 'Documentation AI'
biel_button_style = 'light'           # default | dark | light
biel_button_position = 'bottom-right'

# Widget package version, not the documentation version.
biel_version = 'latest'

# 3. make html

Add search with Ask AI to the layout

Sphinx-biel injects the chat button. For page search with an Ask AI handoff, drop the web component into a _templates/layout.html override. The same template extension Sphinx already uses for theme tweaks. Sits next to the search box your theme ships, or replaces it.

→Drop-in search field in the navbar
→Page results with an Ask AI handoff
→Works alongside Sphinx's built-in search
→No new extension required

_templates/layout.html

{# 1. Add to conf.py:                       #}
{#    templates_path = ['_templates']        #}

{% extends "!layout.html" %}

{% block extrahead %}
{{ super() }}
<link rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css">
<script type="module"
  src="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js">
</script>
{% endblock %}

{% block sidebartitle %}
{{ super() }}
<biel-search-button
  project="<YOUR_PROJECT_ID>"
  header-title="Documentation AI"
  button-style="rounded">
    Search
</biel-search-button>
{% endblock %}

Make your docs queryable by AI agents

Hosted MCP is available from $150/month. Enable it for your Biel project to give compatible AI tools access to the same indexed documentation. Codex, Claude Code, Cursor, and other MCP-compatible assistants can search your Sphinx docs directly. Configure once in mcp.json or your editor’s MCP settings.

→Hosted MCP server, no self-hosting
→Same index as the assistant, one source of truth
→Works with Codex, Claude Code, and Cursor
→Private projects require a project-scoped API key

mcp.json

{
  "mcpServers": {
    "biel-ai": {
      "name": "Biel.ai",
      "type": "http",
      "url": "https://mcp.biel.ai/v2/YOUR_PROJECT_SLUG/mcp"
    }
  }
}

Biel.ai vs built-in Sphinx search

Honest read. Sphinx's built-in JavaScript search is offline-capable, free, and bundled with every project. Read the Docs Search adds server-side indexing across versions. Biel provides its own page-search widget plus an Ask AI handoff to the assistant. Many Sphinx sites run both.

Dimension	Sphinx + RTD search	Biel.ai
Query type	JavaScript keyword index built from searchindex.js at make html time. Title and heading matches.	Semantic page results, with Ask AI for natural-language questions and source-linked answers.
autodoc / autosummary	Indexes function names and headings. Docstring bodies surface as raw text fragments.	Reads docstring content as documentation. Cites specific functions, parameters, return types.
RST and MyST	Same searchindex covers both. Directives and roles are stripped, not interpreted.	Indexes the rendered HTML, so directives, admonitions, and code blocks are read in context.
intersphinx targets	Cross-references resolve at build time but cross-project search is not supported.	Index linked Sphinx projects as additional sources. Answers can cite across project boundaries.
Read the Docs versioning	Each version has its own searchindex. RTD Search adds project-wide ranking; no cross-version answers.	Index published versions. Use separate projects when answers must stay within one version.
Theme support	Built-in search styling tied to each theme; some themes hide it on mobile.	Theme-agnostic web component. Works on sphinx-rtd-theme, furo, pydata-sphinx-theme, custom themes.
Analytics	No content-gap signal. Search queries are not exposed to the project owner.	Unanswered questions, satisfaction trends, and a Content Gaps view that updates daily.
Languages	Per-language stemmers for the languages Sphinx supports.	Answers in 60+ languages, including languages your docs are not written in.
Install	Built into Sphinx and RTD. No install required.	pip install sphinx-biel and three lines in conf.py. Indexing time depends on site size.
Cost	Free, included with Sphinx and Read the Docs.	Self-serve. 14-day free trial, no credit card required.

Before you install

Will it work with my theme?

Yes. sphinx-rtd-theme, furo, pydata-sphinx-theme, sphinx-book-theme, and custom themes are all supported. The widget is a floating button, not a navbar replacement, so it does not depend on theme internals.

Does it understand our API reference?

Yes. Biel reads the published API reference generated from your docstrings and links answers to supporting pages.

Does it work on Read the Docs?

Yes. Install the widget on your published site and index the version URLs you need. Use separate projects when answers must stay within a version. The current page does not automatically limit chat to that version.

Can we keep our existing Sphinx search?

Yes. Keep Sphinx search, replace it with Biel's page-search widget, or run both. The Biel assistant remains a separate surface, and Ask AI can carry a search query into it.

What if our docs span multiple Sphinx projects?

Index each project as a separate source in one Biel.ai project. Answers can cite across project boundaries, which helps when an SDK and a product live in different repos but the same docs ecosystem.

How long does the install take?

Install sphinx-biel and add three lines to conf.py. Indexing time depends on the size and number of versions.

Make your Sphinx docs answer questions

Try Biel with your docs Book a demo

14-day free trial · No credit card required

Use a different platform? See our integration pages for MkDocs, Docusaurus, Starlight, Antora, and Jekyll.