{"id":4266,"library":"sphinxcontrib-websupport","title":"Sphinx Contrib WebSupport","description":"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.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinxcontrib-websupport/","tags":["documentation","sphinx","web","publishing","static-site","rendering"],"install":[{"cmd":"pip install sphinxcontrib-websupport","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","wrong":"from sphinx.websupport import WebSupport","symbol":"WebSupport","correct":"from sphinxcontrib.websupport import WebSupport"}],"quickstart":{"code":"import os\nfrom pathlib import Path\nfrom sphinxcontrib.websupport import WebSupport\n\n# Create dummy Sphinx project directories for the example\nsrc_dir = Path('./docs-src')\nbuild_dir = Path('./docs-build')\n\nsrc_dir.mkdir(exist_ok=True)\nbuild_dir.mkdir(exist_ok=True)\n\n# Create a minimal conf.py and index.rst\n(src_dir / 'conf.py').write_text(\n    \"\"\"project = 'My Web Docs'\\ncopyright = '2023, Me'\\nhtml_theme = 'alabaster'\\n\"\"\"\n)\n(src_dir / 'index.rst').write_text(\n    \"\"\"Welcome to My Web Docs\\n=======================\n\n.. toctree::\n   :maxdepth: 2\n\n   intro\n\"\"\"\n)\n(src_dir / 'intro.rst').write_text(\"\"\"Introduction\\n============\\nThis is an introduction.\"\"\"\n)\n\ntry:\n    # Initialize WebSupport with source and build directories\n    # The build_dir must exist and be writable.\n    support = WebSupport(srcdir=str(src_dir), builddir=str(build_dir))\n\n    # Build all documents\n    print(\"Building documents...\")\n    support.build_all()\n    print(f\"Documents built to: {build_dir}\")\n\n    # Retrieve a specific document (e.g., 'index')\n    print(\"Retrieving 'index' document...\")\n    document = support.get_document('index')\n\n    print(\"\\n--- Document HTML Snippet ---\")\n    print(document.get('body', '')[:200] + '...') # Print first 200 chars of body\n    print(\"\\n--- Document Title ---\")\n    print(document.get('title'))\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up dummy directories\n    import shutil\n    if src_dir.exists():\n        shutil.rmtree(src_dir)\n    if build_dir.exists():\n        shutil.rmtree(build_dir)\n","lang":"python","description":"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."},"warnings":[{"fix":"Update imports to `from sphinxcontrib.websupport import WebSupport`. Ensure `sphinxcontrib-websupport` is installed.","message":"The `websupport` module was moved from core Sphinx to the separate `sphinxcontrib-websupport` package. Old code importing `from sphinx.websupport import WebSupport` will fail.","severity":"breaking","affected_versions":"<1.3 of Sphinx, All versions of sphinxcontrib-websupport"},{"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`.","message":"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.","severity":"breaking","affected_versions":"2.0.0+"},{"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.","message":"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()`.","severity":"breaking","affected_versions":"2.0.0+"},{"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`.","message":"The `builddir` argument provided to `WebSupport` must exist and be writable before calling `build_all()`. `WebSupport` does not automatically create this directory.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}