Feedback widget for Sphinx

Add the PushFeedback widget in a Sphinx project using PIP.

Prerequisites

• A PushFeedback project. Copy its project ID from Projects > your project > Snippet and replace <YOUR_PROJECT_ID> in the examples.
• A Sphinx project.

Install the latest extension release. You can pin a version if needed.

Installation

Floating button

1. Install the Sphinx extension:

   python -m pip install --upgrade sphinx-pushfeedback

2. Add sphinx_pushfeedback to your existing extensions list in conf.py:

   extensions = ['sphinx_pushfeedback']

3. Configure your project ID in the conf.py file:

   pushfeedback_project = '<YOUR_PROJECT_ID>'
   pushfeedback_feedback_button_text = "Feedback"

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

4. Build the documentation:

   make html

   Open your documentation and click Feedback.

Customization

Add the extension’s supported configuration options to your conf.py file, with the following modifications:

1. Prefix configuration options with pushfeedback_. For instance, project would be pushfeedback_project.

2. Use underscores instead of hyphens as words separator. For example, button-position becomes pushfeedback_button_position.

Here's an example:

pushfeedback_button_style = "light"

The extension supports the button position and style, rating, visibility, and text settings registered in its configuration. For options it does not register, such as api-key, escape-close, and the accessible rating labels, use the raw HTML examples below and set attributes on <feedback-button> or <feedback-modal> directly.

Other installation modes

Inline button

1. Install the extension:

   python -m pip install --upgrade sphinx-pushfeedback

2. Configure conf.py. pushfeedback_button_position = "default" suppresses the floating button while keeping the widget assets loaded:

   extensions = ['sphinx_pushfeedback']
   pushfeedback_project = '<YOUR_PROJECT_ID>'
   pushfeedback_button_position = 'default'

3. Place this reStructuredText at the end of your article:

   .. raw:: html
   
      <feedback-button project="<YOUR_PROJECT_ID>" button-position="default" modal-position="center" button-style="dark" screenshot-positioning="true">Feedback</feedback-button>

Embedded form

1. Install the extension:

   python -m pip install --upgrade sphinx-pushfeedback

2. Configure conf.py. pushfeedback_button_position = "default" suppresses the floating button while keeping the widget assets loaded:

   extensions = ['sphinx_pushfeedback']
   pushfeedback_project = '<YOUR_PROJECT_ID>'
   pushfeedback_button_position = 'default'

3. Place this reStructuredText at the end of your article:

   .. raw:: html
   
      <feedback-modal project="<YOUR_PROJECT_ID>" embedded="true"></feedback-modal>

Like and dislike buttons

1. Install the extension:

   python -m pip install --upgrade sphinx-pushfeedback

2. Configure conf.py. pushfeedback_button_position = "default" suppresses the floating button while keeping the widget assets loaded:

   extensions = ['sphinx_pushfeedback']
   pushfeedback_project = '<YOUR_PROJECT_ID>'
   pushfeedback_button_position = 'default'

3. Place this reStructuredText at the end of your article:

   .. raw:: html
   
      <p>Was this helpful?</p>
      <div class="pushfeedback-thumbs-row">
        <feedback-button project="<YOUR_PROJECT_ID>" rating="1" button-position="default" modal-position="center" button-style="default" custom-font="true" screenshot-positioning="true" hide-icon="true">
          <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 10v12"/><path d="M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H3a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L11 2a3.13 3.13 0 0 1 4 3.88Z"/></svg>
          <span class="pushfeedback-thumb-label">Helpful</span>
        </feedback-button>
        <feedback-button project="<YOUR_PROJECT_ID>" rating="0" button-position="default" modal-position="center" button-style="default" custom-font="true" screenshot-positioning="true" hide-icon="true">
          <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M17 14V2"/><path d="M9 18.12 10 14H4.17a2 2 0 0 1-1.92-2.56l2.33-8A2 2 0 0 1 6.5 2H21a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-2.76a2 2 0 0 0-1.79 1.11L13 22a3.13 3.13 0 0 1-4-3.88Z"/></svg>
          <span class="pushfeedback-thumb-label">Not helpful</span>
        </feedback-button>
      </div>

Verify the installation

Run make html, open your documentation, and send a test message. Confirm it appears in your PushFeedback project. Check allowed URLs if submission fails.