{"id":29790234,"url":"https://github.com/miskler/jsoncrack-for-sphinx","last_synced_at":"2026-02-03T03:35:40.276Z","repository":{"id":301983548,"uuid":"1010720142","full_name":"Miskler/jsoncrack-for-sphinx","owner":"Miskler","description":"jsoncrack.com in Sphinks autodoc and manual!","archived":false,"fork":false,"pushed_at":"2025-07-18T23:21:35.000Z","size":160,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-19T02:12:39.659Z","etag":null,"topics":["json","json-schema","sphinx-doc","sphinx-extension"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Miskler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-29T17:02:14.000Z","updated_at":"2025-07-18T23:21:39.000Z","dependencies_parsed_at":"2025-06-30T00:28:51.856Z","dependency_job_id":"0fc919a3-c6a7-46ca-bbc3-17e418ddb7e5","html_url":"https://github.com/Miskler/jsoncrack-for-sphinx","commit_stats":null,"previous_names":["miskler/stoplightio-json-schema-for-sphinx","miskler/json-schema-for-humans-sphinx","miskler/jsoncrack-for-sphinx"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Miskler/jsoncrack-for-sphinx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Miskler%2Fjsoncrack-for-sphinx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Miskler%2Fjsoncrack-for-sphinx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Miskler%2Fjsoncrack-for-sphinx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Miskler%2Fjsoncrack-for-sphinx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Miskler","download_url":"https://codeload.github.com/Miskler/jsoncrack-for-sphinx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Miskler%2Fjsoncrack-for-sphinx/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267442442,"owners_count":24087798,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","json-schema","sphinx-doc","sphinx-extension"],"created_at":"2025-07-28T00:00:35.860Z","updated_at":"2026-02-03T03:35:40.227Z","avatar_url":"https://github.com/Miskler.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSONCrack for Sphinx Extension\n\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/jsoncrack-for-sphinx)\n[![PyPI - Package Version](https://img.shields.io/pypi/v/jsoncrack-for-sphinx?color=blue)](https://pypi.org/project/jsoncrack-for-sphinx/)\n[![Coverage](https://miskler.github.io/jsoncrack-for-sphinx/coverage.svg)](https://miskler.github.io/jsoncrack-for-sphinx/coverage/)\n[![Test Summary](https://miskler.github.io/jsoncrack-for-sphinx/tests-badge.svg)](https://miskler.github.io/jsoncrack-for-sphinx/tests/test-report.html)\n[![Discord](https://img.shields.io/discord/792572437292253224?label=Discord\u0026labelColor=%232c2f33\u0026color=%237289da)](https://discord.gg/UnJnGHNbBp)\n[![Telegram](https://img.shields.io/badge/Telegram-24A1DE)](https://t.me/miskler_dev)\n\n📖 **[Documentation](https://miskler.github.io/jsoncrack-for-sphinx/quickstart)** | 📊 **[Coverage Report](https://miskler.github.io/jsoncrack-for-sphinx/coverage/)** | 🔬 **[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- 🔄 **Automatic schema inclusion**: Schemas are automatically included in autodoc-generated documentation\n- 📁 **Flexible file naming**: Support for multiple naming conventions\n- 🎨 **Beautiful rendering**: Uses JSONCrack for rich interactive visualization\n- 🔧 **Manual inclusion**: `schema` directive for manual schema inclusion\n- 🧪 **Testing support**: Fixtures for testing schema documentation\n- 🌙 **Dark mode**: Support for dark theme styling\n- 📊 **Multiple render modes**: `onclick`, `onload`, and `onscreen` loading modes\n- 🔍 **JSON \u0026\u0026 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├── MyClass.my_method.schema.json        # Method schema\n├── MyClass.my_method.options.schema.json # Method with options\n├── my_function.schema.json              # Function schema\n└── 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- `\u003cClassName\u003e.\u003cmethod\u003e.\u003coption-name\u003e.schema.json`\n- `\u003cClassName\u003e.\u003cmethod\u003e.schema.json`\n- `\u003cfunction\u003e.\u003coption-name\u003e.schema.json`\n- `\u003cfunction\u003e.schema.json`\n\n**Note**: If a function belongs to a class, the class name must be included in the filename.\n\n## Schema Search Policies\n\nThe extension provides powerful and flexible schema file search capabilities through configurable search policies:\n\n### Quick Examples\n\nFor object `perekrestok_api.endpoints.catalog.ProductService.similar`:\n\n**Default (include intermediate paths):**\n```\nProductService.similar.schema.json          # Highest priority\ncatalog.ProductService.similar.schema.json  \nendpoints.catalog.ProductService.similar.schema.json\nsimilar.schema.json\n```\n\n**Skip intermediate paths (cleaner naming):**\n```python\nSearchPolicy(include_path_to_file=False)\n```\n```\nProductService.similar.schema.json          # Only class+method\nsimilar.schema.json                          # Method only\n# Skips: \"catalog.ProductService.similar.schema.json\"\n```\n\n**Directory-based organization:**\n```python\nSearchPolicy(path_to_file_separator=PathSeparator.SLASH)\n```\n```\nProductService.similar.schema.json\nendpoints/catalog/ProductService.similar.schema.json  # Uses directories\nsimilar.schema.json\n```\n\n**Custom API patterns:**\n```python\nSearchPolicy(custom_patterns=['api_{class_name}_{method_name}.json'])\n```\n```\napi_ProductService_similar.json             # Custom pattern\nProductService.similar.schema.json          # Standard patterns\n```\n\n📖 **[Complete Search Patterns Guide](https://miskler.github.io/jsoncrack-for-sphinx/search_patterns.html)** - Detailed analysis of all 8 combinations with examples\n\n## Advanced Schema Search Configuration\n\n### Configurable Search Policy\n\nThe extension supports flexible schema file naming conventions through the `SearchPolicy` configuration. See the [Complete Search Patterns Guide](https://miskler.github.io/jsoncrack-for-sphinx/search_patterns.html) for detailed examples and all possible configurations.\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 (\n    RenderMode, Directions, Theme, ContainerConfig, RenderConfig,\n    SearchPolicy, PathSeparator\n)\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    'search_policy': SearchPolicy(\n        include_package_name=False,  # Include package path in search patterns\n        path_to_file_separator=PathSeparator.DOT,  # How to separate path components\n        path_to_class_separator=PathSeparator.DOT,  # How to separate class/method\n        custom_patterns=['custom_{class_name}_{method_name}.json']  # Additional patterns\n    ),\n    'disable_autodoc': False,  # Disable automatic schema detection\n    'autodoc_ignore': []  # List of paths to ignore in autodoc (uses \"starts with\" logic)\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# Autodoc control\njsoncrack_disable_autodoc = False  # Disable automatic schema detection\njsoncrack_autodoc_ignore = []  # List of paths to ignore in autodoc\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiskler%2Fjsoncrack-for-sphinx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiskler%2Fjsoncrack-for-sphinx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiskler%2Fjsoncrack-for-sphinx/lists"}