Ask AI chatbot widget for Sphinx

Add a Biel.ai AI chatbot or AI search widget to your Sphinx documentation using the sphinx-biel package. Works with any Sphinx theme, including Read the Docs.

Prerequisites

• A Biel.ai account.
• A project with indexed content.
• A Sphinx project.

Add the chatbot widget

The sphinx-biel extension adds a floating chat button to your site.

1. Install the package:

   pip install sphinx-biel

2. Add the extension to your conf.py:

   extensions = ['sphinx_biel']

3. Configure your project ID in conf.py:

   biel_project = '<YOUR_PROJECT_ID>'
   biel_header_title = 'Biel.ai chatbot'
   biel_version = 'latest'

   Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

4. Build and verify:

   make html

   Open the built documentation in a browser and verify the chatbot appears.

Add the search widget

The search widget replaces the theme's search box with Biel.ai's AI-powered search. The sphinx-biel extension already loads the required assets, so overriding one template is all it takes.

1. Create _templates/searchbox.html in your project with the following content:

   <biel-search-button project="<YOUR_PROJECT_ID>" button-style="rounded" header-title="Documentation AI">
     Search
   </biel-search-button>

   Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

2. Make sure conf.py points at your templates directory:

   templates_path = ["_templates"]

3. Rebuild and verify the search widget appears where the theme's search box was (the sidebar on the Read the Docs theme).

Customization

Pass layout options in conf.py with these naming conventions:

• Prefix each option with biel_ (e.g., project → biel_project).
• Replace hyphens with underscores (e.g., button-position → biel_button_position).

biel_button_style = "light"
biel_button_position = "center-right"

Next steps

• Customize the widget's appearance, behavior, and tone.
• Connect integrations like GitHub Actions, MCP, or Zapier.