| Name | jsoncrack-for-sphinx JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Sphinx extension for automatically adding JSON and JSON Schema to documentation |
| upload_time | 2025-07-19 04:11:35 |
| maintainer | None |
| docs_url | None |
| author | Miskler |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# JSONCrack for Sphinx Extension
[](https://github.com/miskler/jsoncrack-for-sphinx/actions/workflows/tests_and_docs.yml)
[](https://badge.fury.io/py/jsoncrack-for-sphinx)
[](https://pypi.org/project/jsoncrack-for-sphinx/)
[](https://miskler.github.io/jsoncrack-for-sphinx/coverage/)
[](https://github.com/miskler/jsoncrack-for-sphinx/actions/workflows/tests_and_docs.yml)
[](https://github.com/miskler/jsoncrack-for-sphinx/actions/workflows/tests_and_docs.yml)
📖 **[Documentation](https://miskler.github.io/jsoncrack-for-sphinx/)** | 📊 **[Coverage Report](https://miskler.github.io/jsoncrack-for-sphinx/coverage/)** | 🔬 **[Examples](https://miskler.github.io/jsoncrack-for-sphinx/examples/)**
This package provides a Sphinx extension that automatically adds JSON schemas to function and method documentation. It uses [jsoncrack.com](https://jsoncrack.com/) to generate beautiful, interactive HTML representations of JSON schemas.
## Features
- 🔄 **Automatic schema inclusion**: Schemas are automatically included in autodoc-generated documentation
- 📁 **Flexible file naming**: Support for multiple naming conventions
- 🎨 **Beautiful rendering**: Uses JSONCrack for rich interactive visualization
- 🔧 **Manual inclusion**: `schema` directive for manual schema inclusion
- 🧪 **Testing support**: Fixtures for testing schema documentation
- 🌙 **Dark mode**: Support for dark theme styling
- 📊 **Multiple render modes**: `onclick`, `onload`, and `onscreen` loading modes
- 🔍 **JSON && Schema**: Supports both JSON schemas (.schema.json) and plain JSON files (.json)
## Installation
```bash
pip install jsoncrack-for-sphinx
```
## Quick Start
### 1. Configure Sphinx
Add the extension to your `conf.py`:
```python
extensions = [
"sphinx.ext.autodoc",
"jsoncrack_for_sphinx",
]
# Configure schema directory
json_schema_dir = os.path.join(os.path.dirname(__file__), "schemas")
```
### 2. Create Schema Files
Create schema files following the naming convention:
```
schemas/
├── MyClass.my_method.schema.json # Method schema
├── MyClass.my_method.options.schema.json # Method with options
├── my_function.schema.json # Function schema
└── my_function.advanced.schema.json # Function with options
```
### 3. Document Your Code
```python
class MyClass:
def my_method(self, data):
"""
Process data according to schema.
Args:
data: Input data (schema automatically included)
"""
pass
```
The schema will be automatically included in the generated documentation!
## File Naming Convention
The extension searches for schema files using these patterns:
- `<ClassName>.<method>.<option-name>.schema.json`
- `<ClassName>.<method>.schema.json`
- `<function>.<option-name>.schema.json`
- `<function>.schema.json`
**Note**: If a function belongs to a class, the class name must be included in the filename.
## Manual Schema Inclusion
You can also manually include schemas using the `schema` directive:
```rst
.. schema:: MyClass.my_method
:title: Custom Title
:description: Custom description
:render_mode: onclick
:direction: RIGHT
:height: 500
```
## Configuration Options
Configure the extension in your `conf.py`:
### New Structured Configuration (Recommended)
```python
from jsoncrack_for_sphinx.config import RenderMode, Directions, Theme, ContainerConfig, RenderConfig
# Required: Directory containing schema files
json_schema_dir = "path/to/schemas"
# JSONCrack configuration
jsoncrack_default_options = {
'render': RenderConfig(
mode=RenderMode.OnClick() # or OnLoad(), OnScreen(threshold=0.1, margin='50px')
),
'container': ContainerConfig(
direction=Directions.RIGHT, # TOP, RIGHT, DOWN, LEFT
height='500', # Height in pixels
width='100%' # Width in pixels or percentage
),
'theme': Theme.AUTO # AUTO, LIGHT, DARK
}
```
### Legacy Configuration (Still Supported)
```python
# Required: Directory containing schema files
json_schema_dir = "path/to/schemas"
# JSONCrack configuration
jsoncrack_render_mode = 'onclick' # 'onclick', 'onload', or 'onscreen'
jsoncrack_theme = None # 'light', 'dark' or None (auto-detect from page)
jsoncrack_direction = 'RIGHT' # 'TOP', 'RIGHT', 'DOWN', 'LEFT'
jsoncrack_height = '500' # Height in pixels
jsoncrack_width = '100%' # Width in pixels or percentage
# Onscreen mode configuration
jsoncrack_onscreen_threshold = 0.1 # Visibility threshold (0.0-1.0)
jsoncrack_onscreen_margin = '50px' # Root margin for early loading
```
### Render Modes
- **`RenderMode.OnClick()`**: Schema loads when user clicks the button (default)
- **`RenderMode.OnLoad()`**: Schema loads immediately when page loads
- **`RenderMode.OnScreen(threshold=0.1, margin='50px')`**: Schema loads automatically when visible
### Render Mode Parameters
- **`threshold`**: Percentage of element that must be visible (0.0-1.0)
- **`margin`**: Distance before element enters viewport to start loading
### Container Configuration
- **`direction`**: Visualization direction (`Directions.TOP`, `RIGHT`, `DOWN`, `LEFT`)
- **`height`**: Container height in pixels (string or int)
- **`width`**: Container width in pixels or percentage (string or int)
### Theme Options
- **`Theme.AUTO`**: Auto-detect from page (default)
- **`Theme.LIGHT`**: Force light theme
- **`Theme.DARK`**: Force dark theme
### File Types
- **`.schema.json`**: JSON Schema files - generates fake data using JSF
- **`.json`**: Plain JSON files - renders the JSON data as-is
## Testing Support
The extension provides fixtures for testing:
```python
from jsoncrack_for_sphinx.fixtures import schema_to_rst_fixture
def test_schema_documentation(schema_to_rst_fixture):
rst_content = schema_to_rst_fixture(schema_path, title="Test Schema")
assert "Test Schema" in rst_content
```
## Development
### Setup
```bash
git clone https://github.com/miskler/jsoncrack-for-sphinx.git
cd jsoncrack-for-sphinx
make install-dev
```
### Commands
```bash
make test # Run tests
make lint # Run linting
make format # Format code
make type-check # Run type checking
make build # Build package
make example-docs # Build example documentation
```
### Example
See the `examples/` directory for a complete working example:
```bash
cd examples/docs
sphinx-build -b html . _build/html
```
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "jsoncrack-for-sphinx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Miskler",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/7d/86/b827c05923f875164827c29f97a8602dff3750a15526187423665e13584a/jsoncrack_for_sphinx-0.1.0.tar.gz",
"platform": null,
"description": "# JSONCrack for Sphinx Extension\n\n[](https://github.com/miskler/jsoncrack-for-sphinx/actions/workflows/tests_and_docs.yml)\n[](https://badge.fury.io/py/jsoncrack-for-sphinx)\n[](https://pypi.org/project/jsoncrack-for-sphinx/)\n[](https://miskler.github.io/jsoncrack-for-sphinx/coverage/)\n[](https://github.com/miskler/jsoncrack-for-sphinx/actions/workflows/tests_and_docs.yml)\n[](https://github.com/miskler/jsoncrack-for-sphinx/actions/workflows/tests_and_docs.yml)\n\n\ud83d\udcd6 **[Documentation](https://miskler.github.io/jsoncrack-for-sphinx/)** | \ud83d\udcca **[Coverage Report](https://miskler.github.io/jsoncrack-for-sphinx/coverage/)** | \ud83d\udd2c **[Examples](https://miskler.github.io/jsoncrack-for-sphinx/examples/)**\n\nThis package provides a Sphinx extension that automatically adds JSON schemas to function and method documentation. It uses [jsoncrack.com](https://jsoncrack.com/) to generate beautiful, interactive HTML representations of JSON schemas.\n\n## Features\n\n- \ud83d\udd04 **Automatic schema inclusion**: Schemas are automatically included in autodoc-generated documentation\n- \ud83d\udcc1 **Flexible file naming**: Support for multiple naming conventions\n- \ud83c\udfa8 **Beautiful rendering**: Uses JSONCrack for rich interactive visualization\n- \ud83d\udd27 **Manual inclusion**: `schema` directive for manual schema inclusion\n- \ud83e\uddea **Testing support**: Fixtures for testing schema documentation\n- \ud83c\udf19 **Dark mode**: Support for dark theme styling\n- \ud83d\udcca **Multiple render modes**: `onclick`, `onload`, and `onscreen` loading modes\n- \ud83d\udd0d **JSON && Schema**: Supports both JSON schemas (.schema.json) and plain JSON files (.json)\n\n## Installation\n\n```bash\npip install jsoncrack-for-sphinx\n```\n\n## Quick Start\n\n### 1. Configure Sphinx\n\nAdd the extension to your `conf.py`:\n\n```python\nextensions = [\n \"sphinx.ext.autodoc\",\n \"jsoncrack_for_sphinx\",\n]\n\n# Configure schema directory\njson_schema_dir = os.path.join(os.path.dirname(__file__), \"schemas\")\n```\n\n### 2. Create Schema Files\n\nCreate schema files following the naming convention:\n\n```\nschemas/\n\u251c\u2500\u2500 MyClass.my_method.schema.json # Method schema\n\u251c\u2500\u2500 MyClass.my_method.options.schema.json # Method with options\n\u251c\u2500\u2500 my_function.schema.json # Function schema\n\u2514\u2500\u2500 my_function.advanced.schema.json # Function with options\n```\n\n### 3. Document Your Code\n\n```python\nclass MyClass:\n def my_method(self, data):\n \"\"\"\n Process data according to schema.\n \n Args:\n data: Input data (schema automatically included)\n \"\"\"\n pass\n```\n\nThe schema will be automatically included in the generated documentation!\n\n## File Naming Convention\n\nThe extension searches for schema files using these patterns:\n\n- `<ClassName>.<method>.<option-name>.schema.json`\n- `<ClassName>.<method>.schema.json`\n- `<function>.<option-name>.schema.json`\n- `<function>.schema.json`\n\n**Note**: If a function belongs to a class, the class name must be included in the filename.\n\n## Manual Schema Inclusion\n\nYou can also manually include schemas using the `schema` directive:\n\n```rst\n.. schema:: MyClass.my_method\n :title: Custom Title\n :description: Custom description\n :render_mode: onclick\n :direction: RIGHT\n :height: 500\n```\n\n## Configuration Options\n\nConfigure the extension in your `conf.py`:\n\n### New Structured Configuration (Recommended)\n\n```python\nfrom jsoncrack_for_sphinx.config import RenderMode, Directions, Theme, ContainerConfig, RenderConfig\n\n# Required: Directory containing schema files\njson_schema_dir = \"path/to/schemas\"\n\n# JSONCrack configuration\njsoncrack_default_options = {\n 'render': RenderConfig(\n mode=RenderMode.OnClick() # or OnLoad(), OnScreen(threshold=0.1, margin='50px')\n ),\n 'container': ContainerConfig(\n direction=Directions.RIGHT, # TOP, RIGHT, DOWN, LEFT\n height='500', # Height in pixels\n width='100%' # Width in pixels or percentage\n ),\n 'theme': Theme.AUTO # AUTO, LIGHT, DARK\n}\n```\n\n### Legacy Configuration (Still Supported)\n\n```python\n# Required: Directory containing schema files\njson_schema_dir = \"path/to/schemas\"\n\n# JSONCrack configuration\njsoncrack_render_mode = 'onclick' # 'onclick', 'onload', or 'onscreen'\njsoncrack_theme = None # 'light', 'dark' or None (auto-detect from page)\njsoncrack_direction = 'RIGHT' # 'TOP', 'RIGHT', 'DOWN', 'LEFT'\njsoncrack_height = '500' # Height in pixels\njsoncrack_width = '100%' # Width in pixels or percentage\n\n# Onscreen mode configuration\njsoncrack_onscreen_threshold = 0.1 # Visibility threshold (0.0-1.0)\njsoncrack_onscreen_margin = '50px' # Root margin for early loading\n```\n\n### Render Modes\n\n- **`RenderMode.OnClick()`**: Schema loads when user clicks the button (default)\n- **`RenderMode.OnLoad()`**: Schema loads immediately when page loads\n- **`RenderMode.OnScreen(threshold=0.1, margin='50px')`**: Schema loads automatically when visible\n\n### Render Mode Parameters\n\n- **`threshold`**: Percentage of element that must be visible (0.0-1.0)\n- **`margin`**: Distance before element enters viewport to start loading\n\n### Container Configuration\n\n- **`direction`**: Visualization direction (`Directions.TOP`, `RIGHT`, `DOWN`, `LEFT`)\n- **`height`**: Container height in pixels (string or int)\n- **`width`**: Container width in pixels or percentage (string or int)\n\n### Theme Options\n\n- **`Theme.AUTO`**: Auto-detect from page (default)\n- **`Theme.LIGHT`**: Force light theme\n- **`Theme.DARK`**: Force dark theme\n\n### File Types\n\n- **`.schema.json`**: JSON Schema files - generates fake data using JSF\n- **`.json`**: Plain JSON files - renders the JSON data as-is\n\n## Testing Support\n\nThe extension provides fixtures for testing:\n\n```python\nfrom jsoncrack_for_sphinx.fixtures import schema_to_rst_fixture\n\ndef test_schema_documentation(schema_to_rst_fixture):\n rst_content = schema_to_rst_fixture(schema_path, title=\"Test Schema\")\n assert \"Test Schema\" in rst_content\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/miskler/jsoncrack-for-sphinx.git\ncd jsoncrack-for-sphinx\nmake install-dev\n```\n\n### Commands\n\n```bash\nmake test # Run tests\nmake lint # Run linting\nmake format # Format code\nmake type-check # Run type checking\nmake build # Build package\nmake example-docs # Build example documentation\n```\n\n### Example\n\nSee the `examples/` directory for a complete working example:\n\n```bash\ncd examples/docs\nsphinx-build -b html . _build/html\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sphinx extension for automatically adding JSON and JSON Schema to documentation",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/miskler/jsoncrack-for-sphinx",
"Issues": "https://github.com/miskler/jsoncrack-for-sphinx/issues",
"Repository": "https://github.com/miskler/jsoncrack-for-sphinx"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7a4e6222cf2df4b02962122707d0c49476b1d41cf8d8bdfbb09f1e6d04b4a643",
"md5": "cef26f411e17eb464b829cb24363ccab",
"sha256": "41471779674a89eea3325a541c399f29ca435182ea8fbf08c8b5333bc0d92772"
},
"downloads": -1,
"filename": "jsoncrack_for_sphinx-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cef26f411e17eb464b829cb24363ccab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18212,
"upload_time": "2025-07-19T04:11:34",
"upload_time_iso_8601": "2025-07-19T04:11:34.534726Z",
"url": "https://files.pythonhosted.org/packages/7a/4e/6222cf2df4b02962122707d0c49476b1d41cf8d8bdfbb09f1e6d04b4a643/jsoncrack_for_sphinx-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d86b827c05923f875164827c29f97a8602dff3750a15526187423665e13584a",
"md5": "ec11dbb3a36b6f0687f402d7ff826480",
"sha256": "493860b8ca7d9174680ec2f5a9ed730a76b3c8c7d14007b0cabf3064f969f3d4"
},
"downloads": -1,
"filename": "jsoncrack_for_sphinx-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ec11dbb3a36b6f0687f402d7ff826480",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42605,
"upload_time": "2025-07-19T04:11:35",
"upload_time_iso_8601": "2025-07-19T04:11:35.871004Z",
"url": "https://files.pythonhosted.org/packages/7d/86/b827c05923f875164827c29f97a8602dff3750a15526187423665e13584a/jsoncrack_for_sphinx-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 04:11:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miskler",
"github_project": "jsoncrack-for-sphinx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jsoncrack-for-sphinx"
}
