For Sphinx & Read the Docs

Ask AI for your Sphinx docs

Q: How long does the install take?

Three lines in conf.py after pip install sphinx-biel. Most teams are live in 15 minutes including indexing the first version.

Drop in an Ask AI chatbot 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.

Start free trial See the install code

14-day freeSelf-serveLive in 15 min

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 teams that take their documentation seriously

Install

Three ways to ship Biel on Sphinx

A floating Ask AI chatbot via sphinx-biel, an AI search field dropped into a layout.html override, or a hosted MCP endpoint Claude and Cursor can query directly. Same indexed content underneath.

Full installation guide

Add the chatbot 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 — no _templates/ overrides needed.

→Floating Ask AI button on every built page
→Works with sphinx-rtd-theme, furo, pydata-sphinx-theme
→Per-version scoping on Read the Docs
→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'

# Read the Docs: scope the chatbot per build.
import os
biel_version = os.environ.get('READTHEDOCS_VERSION', 'latest')

# 3. make html

Add an AI search button to the layout

Sphinx-biel injects the chat button. For an AI search field, 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 AI search field in the navbar
→Returns synthesized answer, not a list
→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

Every Biel project ships with a hosted MCP endpoint. Claude, Cursor, Cline, 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 chatbot, one source of truth
→Works with Claude Desktop, Cursor, Cline, Zed
→Auth via project token, scoped per-workspace

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 is built for natural-language questions with synthesized, autodoc-aware answers. 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.	Natural-language questions. Returns synthesized answers with source citations.
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.	Per-version indexes. Scope answers to the user's current /en// build automatically.
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. Live in 15 minutes.
Cost	Free, included with Sphinx and Read the Docs.	From $50/mo, self-serve. 14-day free trial, no credit card required.

Things teams ask during evaluation

Will it work with my theme?

Yes. sphinx-rtd-theme, furo, pydata-sphinx-theme, sphinx-book-theme, custom themes — 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. API references generated from docstrings (autodoc, autosummary, napoleon-style) are read as documentation, not as keyword fragments. Answers cite the right function and link to its anchor.

Does it work on Read the Docs?

Yes. Same install on Read the Docs as locally. Each version you publish — /en/latest/, /en/stable/, tagged releases — is indexed separately, and the chatbot scopes answers to the version the reader is on.

Can we keep our existing Sphinx search?

Yes. The Ask AI button sits alongside the built-in search, not in place of it. Readers pick the surface that matches what they need — keyword lookup or natural-language questions.

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 — useful when an SDK and a product live in different repos but the same docs ecosystem.

How long does the install take?

Three lines in conf.py after pip install sphinx-biel. Most teams are live in 15 minutes including indexing the first version.

Where does our content go?

EU-hosted by default. GDPR compliant. Your content is never used to train models.

Make your Sphinx docs answer questions

Start free trial Book a demo

14-day free trial · No credit card required · From $50/mo

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