All Collections
CMS & Deployment
Integrate with Sphinx Documentation Using ReadTheDocs Theme
Integrate with Sphinx Documentation Using ReadTheDocs Theme

Greatly enhance the feedback process by allowing users to directly interact with your documentation pages

Joe Scanlon avatar
Written by Joe Scanlon
Updated over a week ago

Integrating the widget into your Sphinx-based documentation can greatly enhance the feedback process by allowing users to directly interact with your documentation pages. This guide provides a concise and clear path to embedding the widget across all pages of your Sphinx documentation. We assume you are using the sphinx_rtd_theme, popular for its clean and professional appearance.

Step 1: Identify and Prepare the HTML Template

Goal: Prepare to modify the base HTML template to include the widget.


  1. Locate the Template: If you're using the sphinx_rtd_theme, the default layout file (layout.html) typically resides within the theme's template directory. Direct modifications to this file are not recommended, as updates to the theme could overwrite your changes.

  2. Create a Custom Template Directory:

    • Navigate to your Sphinx project directory.

    • Create a new directory named _templates if it does not already exist:

      mkdir _templates

Step 2: Customize the Base Template

Goal: Integrate the JavaScript into a custom template to ensure it appears on every page.


  1. Create a Custom Template File:

    • Inside the _templates directory, create or edit a file named layout.html.

    • Add the following content to extend the default layout and embed the script:

      {# _templates/layout.html #}
      {% extends "!layout.html" %}

      {% block footer %}
      {{ super() }}

      ###### snippet code goes here!

      {% endblock %}
    • This template code extends the existing layout.html file and injects the script just before the end of the <footer> block, ensuring it loads on every page.

Step 3: Configure Sphinx to Use the Custom Template

Goal: Direct Sphinx to use your custom template for HTML generation.


  • Open your file located in the project root directory.

  • Add or update the templates_path variable to include _templates:

    templates_path = ['_templates']

Step 4: Build Your Documentation

Goal: Generate your documentation with the integrated widget.


  • From your Sphinx project directory, execute the following command:

    make html
  • This command compiles the documentation into HTML, incorporating the widget across all pages.

Step 5: Verify the Integration

Goal: Ensure the widget is functioning correctly on all pages.


  • Navigate to the _build/html directory.

  • Open various HTML files in your browser to confirm that the widget appears and functions as expected on each page.


By following these steps, you have successfully integrated the widget into your Sphinx documentation, using the ReadTheDocs theme. This integration allows for seamless user interaction and feedback, enhancing the usability and effectiveness of your documentation.

Did this answer your question?