Skip to main content

Add AI to Sphinx

Integrate the kapa.ai chat widget into your Sphinx documentation to enable users to ask natural language questions about your product, significantly enhancing user experience by providing quick and accurate answers.

Prerequisites​

Before adding the widget to your Sphinx site, you'll need to:

  1. Ensure you have a kapa.ai project set up with your knowledge sources added
  2. Follow the general installation instructions to enabled your domain and obtain your Website ID

Installation​

1. Create Custom JavaScript File​

Create a new file named custom.js in your Sphinx project's _static directory:

document.addEventListener("DOMContentLoaded", function () {
  var script = document.createElement("script");
  script.src = "https://widget.kapa.ai/kapa-widget.bundle.js";
  script.setAttribute("data-website-id", "XXX-XXX-XXX");
  script.setAttribute("data-project-name", "PROJECT_NAME");
  script.setAttribute("data-project-color", "#HEX_COLOR_CODE");
  script.setAttribute("data-project-logo", "https://LINK_TO_LOGO.com/logo.png");
  script.async = true;
  document.head.appendChild(script);
});

2. Add Custom CSS​

Create a new file named custom.css in your _static directory to ensure correct widget positioning:

#kapa-widget-container {
  z-index: 10000 !important;
  position: absolute !important;
}

.mantine-Modal-root {
  z-index: 10000;
  position: absolute;
}

3. Update Sphinx Configuration​

Add the following to your conf.py file to include the custom files:

html_static_path = ["_static"]
html_js_files = ["custom.js"]
html_css_files = ["custom.css"]

4. Build and Deploy​

Rebuild your Sphinx documentation to apply the changes:

make html
Customization Options

To tailor the widget to your brand and specific needs, visit our Configuration page. You'll find detailed instructions on how to adjust colors, logos, and other widget properties by modifying the attributes in custom.js.

note

Make sure your _static directory is properly included in your build process and that the paths in conf.py are correct relative to your project structure.