Sphinx Comments

Common errors

• sphinx-build: WARNING: autodoc: failed to import module 'your_module_name'

  cause Sphinx, or any of its extensions (including sphinx-comments if it had Python components that needed importing), cannot find your project's Python modules or `conf.py` due to incorrect `sys.path` configuration or being run from the wrong directory.
  fix In your `conf.py`, add your project's root directory to `sys.path`. For example, if `conf.py` is in `docs/`, add `sys.path.insert(0, os.path.abspath('..'))` at the top. Also, ensure `sphinx-build` is executed from the correct directory (usually the one containing `conf.py` or its parent).

• Commenting box/overlay does not appear on generated Sphinx pages or shows an error message.

  cause The `comments_config` dictionary in `conf.py` is either missing, incorrectly configured, or the required external JavaScript for the chosen commenting service is not loading correctly.
  fix Verify that `sphinx_comments` is correctly listed in `extensions`. Double-check the `comments_config` dictionary for the chosen engine against the official documentation (e.g., 'repo' must be provided for utteranc.es). Inspect your browser's developer console for JavaScript errors related to the commenting service.

Warnings

• gotcha Attempting to activate multiple commenting engines simultaneously via `comments_config` is not supported. Users must select only one commenting platform to enable at a time.
  Fix: Ensure that `comments_config` only defines configuration for a single commenting engine (e.g., either 'hypothesis' or 'utterances', but not both).
• gotcha The primary documentation for sphinx-comments was last updated in September 2020. While the library itself is at version 0.0.3, newer Sphinx versions or changes in third-party commenting services might not be fully reflected in the existing documentation, potentially leading to minor configuration discrepancies.
  Fix: Refer to the GitHub repository's `README.md` or recent issues for any un-documented changes or updated configuration examples, and test thoroughly with your specific Sphinx version.
• gotcha As `conf.py` is a Python file, common Python syntax errors (e.g., missing commas, incorrect indentation, mismatched quotes) within the `extensions` list or `comments_config` dictionary will cause Sphinx builds to fail with often generic error messages.
  Fix: Carefully review `conf.py` for Python syntax errors. Pay close attention to commas in lists and dictionaries, and ensure correct indentation, especially for multi-line configurations.

Install

• pip install sphinx-comments Install latest version

Imports

• sphinx_comments

  extensions = ['sphinx_comments']

  Used as a string in Sphinx's conf.py extensions list; no direct Python import statement is typically needed by users.

Quickstart

To quickly integrate sphinx-comments, first install it via pip. Then, modify your Sphinx project's `conf.py` file to include 'sphinx_comments' in the `extensions` list. Finally, define a `comments_config` dictionary, choosing and configuring your desired commenting engine (e.g., Hypothes.is or utteranc.es) according to the library's documentation. Ensure to replace placeholder values like 'your-github-org/your-github-repo' if using utteranc.es.

import os
import sys

# conf.py

# Basic project information
project = 'My Commented Docs'
copyright = '2026, My Organization'
author = 'Doc Creator'

# Add 'sphinx_comments' to your extensions list
extensions = [
    'sphinx.ext.autodoc', # A commonly used Sphinx extension
    'sphinx_comments',
]

# Configure the commenting engine. Choose one and provide its configuration.
# Example 1: Activate Hypothes.is
comments_config = {
   "hypothesis": True
}

# Example 2: Activate utteranc.es (requires a GitHub repository for issues)
# comments_config = {
#    "utterances": {
#        "repo": "your-github-org/your-github-repo", # REQUIRED: Replace with your repo
#        "issue-term": "pathname", # or 'url', 'title', 'og:title'
#        "theme": "github-light", # or 'github-dark', 'preferred-color-scheme', etc.
#        "label": "discussion", # Optional: label for new issues
#    }
# }

# Example 3: Activate dokie.li (experimental)
# comments_config = {
#    "dokieli": True
# }

# Set your desired HTML theme
html_theme = 'alabaster'