Feedback widget for Sphinx

PushFeedback collects user feedback directly from your website. This guide covers installation in a Sphinx project using PIP.

Prerequisites

Before you begin, you need:

• A PushFeedback account. If you don't have one, sign up for free.
• A project created in your PushFeedback dashboard. If you haven't created one yet, follow the steps in the Quickstart guide.
• A Sphinx project.

Installation

Floating button

1. Install the Sphinx extension:

   pip install sphinx-pushfeedback

2. Add the extension to your Sphinx project's conf.py file:

   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

   Once built, open your documentation in a web browser. Verify that the feedback button appears and works correctly on your site.

Customization

Add any configuration option 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"

Other installation modes

Inline button

1. Install the extension:

   pip install 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 or in a template:

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

Embedded form

1. Install the extension:

   pip install 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 or in a template:

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

Like and dislike buttons

1. Install the extension:

   pip install 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 or in a template:

   .. 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">
          <span class="pushfeedback-thumb-label">Helpful</span>
          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 9V5a3 3 0 0 0-3-3l-4 9v11h11.28a2 2 0 0 0 2-1.7l1.38-9a2 2 0 0 0-2-2.3zM7 22H4a2 2 0 0 1-2-2v-7a2 2 0 0 1 2-2h3" /></svg>
        </feedback-button>
        <feedback-button project="<YOUR_PROJECT_ID>" rating="0" button-position="default" modal-position="center" button-style="default" custom-font="true">
          <span class="pushfeedback-thumb-label">Not helpful</span>
          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10 15v4a3 3 0 0 0 3 3l4-9V2H5.72a2 2 0 0 0-2 1.7l-1.38 9a2 2 0 0 0 2 2.3zm7-13h2.67A2.31 2.31 0 0 1 22 4v7a2.31 2.31 0 0 1-2.33 2H17" /></svg>
        </feedback-button>
      </div>