Registry /
web-framework / sphinxcontrib-websupport
Install & Compatibility
Where this runs
tested against v2.0.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 1.106s · 92.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.3s · import 1.028s · 93MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WebSupport
✓ from sphinxcontrib.websupport import WebSupport
✗ from sphinx.websupport import WebSupport
The websupport module was moved out of core Sphinx into `sphinxcontrib-websupport` around Sphinx 1.3. Importing from `sphinx.websupport` will fail for modern Sphinx/websupport installations.
This quickstart demonstrates how to initialize `WebSupport`, build Sphinx documentation, and retrieve generated content. It creates a dummy Sphinx project, builds it using `WebSupport.build_all()`, and then fetches the content of the 'index' page.
import os
from pathlib import Path
from sphinxcontrib.websupport import WebSupport
# Create dummy Sphinx project directories for the example
src_dir = Path('./docs-src')
build_dir = Path('./docs-build')
src_dir.mkdir(exist_ok=True)
build_dir.mkdir(exist_ok=True)
# Create a minimal conf.py and index.rst
(src_dir / 'conf.py').write_text(
"""project = 'My Web Docs'\ncopyright = '2023, Me'\nhtml_theme = 'alabaster'\n"""
)
(src_dir / 'index.rst').write_text(
"""Welcome to My Web Docs\n=======================
.. toctree::
:maxdepth: 2
intro
"""
)
(src_dir / 'intro.rst').write_text("""Introduction\n============\nThis is an introduction."""
)
try:
# Initialize WebSupport with source and build directories
# The build_dir must exist and be writable.
support = WebSupport(srcdir=str(src_dir), builddir=str(build_dir))
# Build all documents
print("Building documents...")
support.build_all()
print(f"Documents built to: {build_dir}")
# Retrieve a specific document (e.g., 'index')
print("Retrieving 'index' document...")
document = support.get_document('index')
print("\n--- Document HTML Snippet ---")
print(document.get('body', '')[:200] + '...') # Print first 200 chars of body
print("\n--- Document Title ---")
print(document.get('title'))
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up dummy directories
import shutil
if src_dir.exists():
shutil.rmtree(src_dir)
if build_dir.exists():
shutil.rmtree(build_dir)
Debug
Known issues
breakingThe `websupport` module was moved from core Sphinx to the separate `sphinxcontrib-websupport` package. Old code importing `from sphinx.websupport import WebSupport` will fail.fixUpdate imports to `from sphinxcontrib.websupport import WebSupport`. Ensure `sphinxcontrib-websupport` is installed.
affects: <1.3 of Sphinx, All versions of sphinxcontrib-websupport
breakingVersion 2.0.0 completely removed `SQLAlchemy` support and the built-in storage backend. Users who relied on the default storage mechanism will need to implement their own storage solution.fixIf upgrading from <2.0.0 and using default storage, you must now provide a custom storage backend (e.g., using `MongoDB`, file system, etc.) and integrate it with `WebSupport`.
affects: 2.0.0+
breakingSeveral deprecated APIs were removed in version 2.0.0, including the `storage` and `json_serializer` arguments to the `WebSupport` constructor, and methods like `get_comments()` and `add_comment()`.fixReview the 2.0.0 changelog. Replace `json_serializer` usage with `json.dump()` and `WebSupport.json_compact`. For storage, provide a custom solution. `get_search_results()` now returns a `SearchResults` object instead of a list of dicts.
affects: 2.0.0+
gotchaThe `builddir` argument provided to `WebSupport` must exist and be writable before calling `build_all()`. `WebSupport` does not automatically create this directory.fixEnsure the specified `builddir` path exists and has appropriate write permissions (e.g., `pathlib.Path(build_dir).mkdir(parents=True, exist_ok=True)`) before initializing `WebSupport`.
affects: All versions
Upgrade
Version history
2.0.0latest on PyPI · released Jul 29, 2024
Audit
Dependencies
No dependency data recorded yet.