Install & Compatibility
Where this runs
tested against v0.0.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.3s · import 0.000s · 93MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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'
Debug
Known issues
gotchaAttempting to activate multiple commenting engines simultaneously via `comments_config` is not supported. Users must select only one commenting platform to enable at a time.fixEnsure that `comments_config` only defines configuration for a single commenting engine (e.g., either 'hypothesis' or 'utterances', but not both).
affects: All versions
gotchaThe 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.fixRefer 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.
affects: All versions, especially with newer Sphinx installations
gotchaAs `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.fixCarefully 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.
affects: All versions
Upgrade
Version history
0.0.3latest on PyPI · released Aug 12, 2020
Audit
Dependencies
SphinxrequiredThis is a Sphinx extension and requires Sphinx to function.