Skip to main content

Ask AI assistant widget for Sphinx

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

Prerequisites​

Add the assistant widget​

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

Assistant widget for docs

  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 assistant'
    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 assistant appears.

Add the search widget​

The search widget replaces the theme's search box with Biel.ai's AI-powered search. Enable sphinx-biel to load the widget assets, then override the search template.

Biel search

  1. Install and configure the extension:

    pip install sphinx-biel

    In conf.py, append sphinx_biel to your existing extensions and set your project ID:

    extensions = ['sphinx_biel']
    biel_project = '<YOUR_PROJECT_ID>'
    biel_header_title = 'Documentation AI'

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

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

    templates_path = ["_templates"]

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

Select a widget version​

The extension loads the widget's JavaScript and CSS from the CDN using latest by default. You do not need to install an npm widget package. Your Python dependencies do not pin these browser assets.

To use a specific widget release, add this to conf.py and rebuild with make html:

biel_version = '0.1.93'

Replace 0.1.93 with your chosen release. Set biel_version = 'latest' to follow new releases again. See CDN version selection for how caching affects latest.

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​