Sphinx Contrib WebSupport

2.0.0 · active · verified Sat Apr 11

sphinxcontrib-websupport provides a Python API to easily integrate Sphinx documentation into your Web application. It facilitates building Sphinx documentation in a web-friendly format and retrieving content. The current version is 2.0.0, and releases are infrequent but can include significant breaking changes between major versions.

Warnings

breaking The `websupport` module was moved from core Sphinx to the separate `sphinxcontrib-websupport` package. Old code importing `from sphinx.websupport import WebSupport` will fail.
Fix: Update imports to `from sphinxcontrib.websupport import WebSupport`. Ensure `sphinxcontrib-websupport` is installed.
breaking Version 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.
Fix: If 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`.
breaking Several 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()`.
Fix: Review 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.
gotcha The `builddir` argument provided to `WebSupport` must exist and be writable before calling `build_all()`. `WebSupport` does not automatically create this directory.
Fix: Ensure 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`.

Install

pip install sphinxcontrib-websupport Install latest version

Imports

WebSupport
```
from sphinxcontrib.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.

Quickstart

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)

view raw JSON →