{"id":3812,"library":"sphinxcontrib-redoc","title":"Sphinxcontrib-redoc","description":"Sphinxcontrib-redoc is a Sphinx extension that renders OpenAPI (formerly Swagger) specifications using the ReDoc library. It integrates interactive API documentation directly into Sphinx-generated documentation. The current version is 1.6.0, released in April 2020, indicating that the project is in a maintenance state with infrequent updates.","status":"maintenance","version":"1.6.0","language":"en","source_language":"en","source_url":"https://github.com/ikalnytskyi/sphinxcontrib-redoc","tags":["sphinx","openapi","redoc","documentation","rest","api"],"install":[{"cmd":"pip install sphinxcontrib-redoc","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The extension is enabled by adding 'sphinxcontrib.redoc' to the 'extensions' list in Sphinx's conf.py.","symbol":"sphinxcontrib.redoc","correct":"extensions = ['sphinxcontrib.redoc']"}],"quickstart":{"code":"# conf.py\nimport os\n\nproject = 'My API Docs'\ncopyright = '2026, Your Name'\nextensions = [\n    'sphinxcontrib.redoc',\n    'sphinx.ext.autodoc', # Example of another common extension\n]\n\n# Configure sphinxcontrib-redoc\nredoc = [\n    {\n        'name': 'My Awesome API',\n        'page': 'api/index', # Output HTML page path relative to build directory\n        'spec': 'openapi.yaml', # Path to OpenAPI spec relative to conf.py\n        'embed': True, # Embed the spec into the HTML page\n        'opts': {\n            'lazy-rendering': True,\n            'native-scrollbars': True,\n            'hide-hostname': True,\n            'expand-responses': ['200', '201'],\n        }\n    },\n]\n\n# Example of a minimal index.rst or api/index.rst\n# My Awesome API\n# ==============\n#\n# .. toctree::\n#    :maxdepth: 2\n#\n# .. raw:: html\n#\n#    <div id=\"redoc-container\"></div>\n\n# Make sure the openapi.yaml exists in your docs folder for a local spec.\n# Or use a remote URL: 'spec': 'https://petstore.swagger.io/v2/swagger.json'","lang":"python","description":"To quickly integrate sphinxcontrib-redoc, first install the package. Then, enable the extension by adding 'sphinxcontrib.redoc' to the `extensions` list in your Sphinx `conf.py`. Define your OpenAPI specifications using the `redoc` configuration variable, which is a list of dictionaries. Each dictionary specifies the API's name, the output HTML page path, the path (local or URL) to the OpenAPI spec, and optional ReDoc rendering options. You must also create an RST file (e.g., `api/index.rst`) for each defined page to ensure it's included in Sphinx's table of contents and provides a target for the rendered documentation."},"warnings":[{"fix":"Upgrade your Python environment to 3.5 or later.","message":"Version 1.6.0 dropped official support for Python 3.4. Ensure you are using Python 3.5 or newer.","severity":"breaking","affected_versions":">=1.6.0"},{"fix":"Consider using ReDoc options like `lazy-rendering` or `native-scrollbars` in your `redoc` configuration to mitigate performance impact for large specs.","message":"ReDoc can experience performance issues when rendering very large or complex OpenAPI specifications, leading to slow page load times in the generated documentation.","severity":"gotcha","affected_versions":"All"},{"fix":"For embedded specs, provide a local file path for the 'spec' option. For external specs, set `embed: False`.","message":"When `embed` is set to `True`, the extension currently does not support embedding OpenAPI specifications from external HTTP(s) links; only local file paths are supported for embedding.","severity":"gotcha","affected_versions":"All"},{"fix":"Currently, there is no official fix from `sphinxcontrib-redoc`. You may need to ignore this warning or monitor upstream for updates.","message":"As of Sphinx 8, subsequent builds may produce a `WARNING: Aborted attempted copy from ... redoc.js` message. While often harmless, it can clutter build logs.","severity":"gotcha","affected_versions":"Sphinx >= 8, sphinxcontrib-redoc < 2.0 (if ever released)"},{"fix":"Override the `redoc_uri` Sphinx option to point to a more current ReDoc CDN, e.g., `redoc_uri = 'https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js'`.","message":"The `redoc.js` library bundled with `sphinxcontrib-redoc` (last updated with v1.21.2 in 1.4.0, with minor updates up to 1.6.0) is potentially outdated. Newer ReDoc versions offer better features and bug fixes.","severity":"gotcha","affected_versions":"All"},{"fix":"You must explicitly create a stub `.rst` file (e.g., `api.rst` or `api/index.rst`) and include it in your main `toctree` directive within your Sphinx project. This file will then be overwritten or used as the target for the ReDoc output.","message":"The HTML page generated by `sphinxcontrib-redoc` is not automatically included in Sphinx's `toctree` (table of contents).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}