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 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.

Add Biel to Sphinx 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.

100,000+ technical questions answered, 98.7% rated helpful

Install

Three ways to ship Biel on Sphinx

A floating Ask AI chatbot 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 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, with 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 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

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 provides its own page-search widget plus an Ask AI handoff to the chatbot. 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.	Keyword 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.	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.	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, 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. 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. Keep Sphinx search, replace it with Biel's page-search widget, or run both. The Biel chatbot 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

Build your assistant 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.