Sphinx Integration

Enhance your Sphinx documentation with Ask0's AI assistant. Learn how to integrate intelligent search and chat into your Python documentation built with Sphinx.

Add Ask0 to your Sphinx documentation site.

Installation

Custom HTML Template

Create a custom template that extends the base:

_templates/layout.html

{% extends "!layout.html" %}

{% block footer %}
  {{ super() }}
  <script
    src="https://assets.ask0.ai/scripts/ask.js"
    data-project-id="{{ ask0_project_id }}"
    async
  ></script>
{% endblock %}

Configuration

Update your Sphinx configuration:

conf.py

project = 'My Documentation'
author = 'Your Name'

templates_path = ['_templates']

html_context = {
    'ask0_project_id': 'YOUR_PROJECT_ID',
}

html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    'navigation_depth': 4,
}

Read the Docs Theme

For the Read the Docs theme:

conf.py

html_theme = 'sphinx_rtd_theme'

html_js_files = [
    ('https://assets.ask0.ai/scripts/ask.js', {
        'async': 'async',
        'data-project-id': 'YOUR_PROJECT_ID',
    }),
]

Furo Theme

For the modern Furo theme:

conf.py

html_theme = 'furo'

html_theme_options = {
    "footer_icons": [
        {
            "name": "GitHub",
            "url": "https://github.com/yourusername/yourproject",
            "html": "",
            "class": "",
        },
    ],
}

html_js_files = [
    ('https://assets.ask0.ai/scripts/ask.js', {
        'async': 'async',
        'data-project-id': 'YOUR_PROJECT_ID',
    }),
]

Custom Extension

Create a Sphinx extension for more control:

_ext/ask0.py

from docutils import nodes
from sphinx.application import Sphinx

def setup(app: Sphinx):
    app.add_config_value('ask0_project_id', '', 'html')

    def add_ask0_script(app, pagename, templatename, context, doctree):
        project_id = app.config.ask0_project_id
        if project_id:
            script = f'''
            <script
                src="https://assets.ask0.ai/scripts/ask.js"
                data-project-id="{project_id}"
                async
            ></script>
            '''
            metatags = context.get('metatags', '')
            context['metatags'] = metatags + script

    app.connect('html-page-context', add_ask0_script)

    return {
        'version': '0.1',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

Then enable it:

conf.py

import sys
import os

sys.path.insert(0, os.path.abspath('_ext'))

extensions = [
    'ask0',
    # ... other extensions
]

ask0_project_id = 'YOUR_PROJECT_ID'

Sphinx Tips:

Use template overrides for custom HTML
Store project ID in conf.py
Works with all major Sphinx themes
Test with make html before deploying
Compatible with Read the Docs hosting

Sphinx Integration

Installation

Custom HTML Template

Configuration

Read the Docs Theme

Furo Theme

Custom Extension

Next Steps

On this page