Sphinx Data Viewer

0.1.5 · active · verified Thu Apr 16

Sphinx Data Viewer is a Sphinx extension that provides an interactive list view for presenting JSON and Python data within your documentation. It allows users to display structured data directly from inline content, JSON files, or Python objects. The library is currently at version 0.1.5, released on August 28, 2024, and maintains an active development cadence tied to Sphinx compatibility.

Common errors

```
Sphinx build fails with errors related to 'add_css_file' or 'add_js_file' after updating Sphinx.
```
cause Using an older version of `sphinx-data-viewer` that relies on deprecated Sphinx APIs for managing CSS/JS assets.

fix Upgrade `sphinx-data-viewer` to version 0.1.5 or later: `pip install --upgrade sphinx-data-viewer`.
```
WARNING: Unknown directive type "data-viewer".
```
cause The `sphinx_data_viewer` extension has not been correctly added to the `extensions` list in your Sphinx project's `conf.py` file.

fix Open your `conf.py` and ensure `"sphinx_data_viewer"` is present in the `extensions` list.
```
Data specified in `data-viewer` directive is not displayed or appears malformed in the output.
```
cause This typically occurs due to invalid JSON syntax for inline data, incorrect file paths for the `:file:` option, or the specified Python variable for `:var:` not being accessible or correctly defined in `conf.py`.

fix Carefully check the JSON syntax for correctness, verify file paths (absolute or relative to the current document), or ensure the Python variable is correctly named and available in the `conf.py` scope.

Warnings

breaking Version 0.1.5 fixed deprecations related to Sphinx's handling of CSS/JS assets. Older versions of sphinx-data-viewer (pre-0.1.5) may cause build failures or display issues with newer Sphinx versions due to these changes.
Fix: Upgrade to sphinx-data-viewer version 0.1.5 or newer: `pip install --upgrade sphinx-data-viewer`.
gotcha The `:expand:` option for the `data-viewer` directive is a flag and does not require a value. Providing a value or incorrect syntax (e.g., `:expand: True`) can lead to the option not being recognized or unexpected behavior.
Fix: Simply include `:expand:` without any value to enable it, like this: `.. data-viewer:: :expand: { ... }`.

Install

pip install sphinx-data-viewer Install stable version

Imports

sphinx_data_viewer
```
# In conf.py
extensions = [
    "sphinx_data_viewer"
]
```
Sphinx Data Viewer is a Sphinx extension, not a Python library with direct runtime imports. It is enabled by adding its module name to the 'extensions' list in Sphinx's conf.py configuration file.

Quickstart

To get started with Sphinx Data Viewer, first install the package. Then, enable the extension by adding 'sphinx_data_viewer' to the `extensions` list in your Sphinx project's `conf.py` file. Finally, use the `.. data-viewer::` reStructuredText directive in your documentation files to display inline JSON, content from a JSON file, or data from a Python variable defined in `conf.py`. The `:expand:` option can be used to show the complete data by default.

# 1. Install the library:
# pip install sphinx-data-viewer

# 2. Add 'sphinx_data_viewer' to your conf.py extensions list:
# In docs/conf.py
# extensions = [
#     'sphinx.ext.autodoc',
#     'sphinx.ext.napoleon',
#     'sphinx_data_viewer'  # Add this line
# ]

# 3. Use the data-viewer directive in a reStructuredText file (e.g., index.rst):
# .. data-viewer::
#    :title: Example Data
#    :expand:
#
#    {
#        "name": "Alice",
#        "age": 30,
#        "is_student": false,
#        "courses": ["Math", "Science"]
#    }

# You can also load data from a file:
# .. data-viewer::
#    :file: my_data.json

# Or from a Python variable defined in conf.py:
# # In conf.py:
# # my_python_data = {'city': 'New York', 'population': 8000000}
# # In .rst file:
# # .. data-viewer::
# #    :var: my_python_data

view raw JSON →