{"id":9317,"library":"sphinx-comments","title":"Sphinx Comments","description":"Sphinx Comments is a lightweight Sphinx extension that adds comments and annotation functionality to your Sphinx documentation websites. It currently supports integration with popular commenting engines such as Hypothes.is, utteranc.es, and dokie.li. The library is currently at version 0.0.3, with an irregular release cadence that primarily reflects updates to supported commenting platforms or minor Sphinx compatibility adjustments.","status":"active","version":"0.0.3","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-comments","tags":["sphinx","documentation","comments","annotation","extension"],"install":[{"cmd":"pip install sphinx-comments","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to function.","package":"Sphinx","optional":false}],"imports":[{"note":"Used as a string in Sphinx's conf.py extensions list; no direct Python import statement is typically needed by users.","symbol":"sphinx_comments","correct":"extensions = ['sphinx_comments']"}],"quickstart":{"code":"import os\nimport sys\n\n# conf.py\n\n# Basic project information\nproject = 'My Commented Docs'\ncopyright = '2026, My Organization'\nauthor = 'Doc Creator'\n\n# Add 'sphinx_comments' to your extensions list\nextensions = [\n    'sphinx.ext.autodoc', # A commonly used Sphinx extension\n    'sphinx_comments',\n]\n\n# Configure the commenting engine. Choose one and provide its configuration.\n# Example 1: Activate Hypothes.is\ncomments_config = {\n   \"hypothesis\": True\n}\n\n# Example 2: Activate utteranc.es (requires a GitHub repository for issues)\n# comments_config = {\n#    \"utterances\": {\n#        \"repo\": \"your-github-org/your-github-repo\", # REQUIRED: Replace with your repo\n#        \"issue-term\": \"pathname\", # or 'url', 'title', 'og:title'\n#        \"theme\": \"github-light\", # or 'github-dark', 'preferred-color-scheme', etc.\n#        \"label\": \"discussion\", # Optional: label for new issues\n#    }\n# }\n\n# Example 3: Activate dokie.li (experimental)\n# comments_config = {\n#    \"dokieli\": True\n# }\n\n# Set your desired HTML theme\nhtml_theme = 'alabaster'\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure that `comments_config` only defines configuration for a single commenting engine (e.g., either 'hypothesis' or 'utterances', but not both).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially with newer Sphinx installations"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","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.","error":"sphinx-build: WARNING: autodoc: failed to import module 'your_module_name'"},{"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.","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.","error":"Commenting box/overlay does not appear on generated Sphinx pages or shows an error message."}]}