{"author":"Leo Noordergraaf","author_email":"leo@noordergraaf.net","bugtrack_url":null,"classifiers":["Development Status :: 4 - Beta","Environment :: Plugins","Framework :: Sphinx :: Extension","Intended Audience :: Developers","License :: OSI Approved :: GNU General Public License v3 (GPLv3)","Operating System :: OS Independent","Programming Language :: Python :: 3","Topic :: Documentation :: Sphinx","Topic :: Software Development :: Documentation"],"description":".. sphinx-jsonschema README\n Copyright: (C) 2017-2020, Leo Noordergraaf\n\n=================\nsphinx-jsonschema\n=================\n\nThis package contains sphinx-jsonschema, an extension to Sphinx to allow\nauthors to display a `JSON Schema `_ in their\ndocumentation.\n\nA dockerized version can be found at: `Extended Sphinx `_.\n\nIt arose out of a personal itch and implements what I needed.\nSome features of JSON Schema are (not yet) implemented.\nAlso I can imagine that other display layouts are desired.\n\nLet me know in comments and perhaps pull requests.\n\n\nFeatures\n========\n\n* Near complete support for all features of JSON Schema Draft 4.\n* Supports inline schemas as well as external schemas loaded from a file or URL.\n* Supports JSON Pointer notation on external resources to select a subschema.\n* Supports cross references between schemas.\n* Allows reStructuredText markup in ``title`` and ``description`` fields.\n* Allows JSON Schema definitions in both JSON and YAML format.\n* Supports the ``examples`` keyword from Draft 7.\n\nInstallation\n============\nInstall the package using pip::\n\n pip install sphinx-jsonschema\n\nand add it to the extensions list in your conf.py::\n\n extensions = [\n 'sphinx-jsonschema'\n ]\n\nUsage\n=====\n\nThe extension adds a single directive to Sphinx: **jsonschema**.\nYou provide it with either an http URL to a schema or you may\nembed the schema inline.\n\nExample\n=======\n\nDisplay a schema fetched from a website::\n\n .. jsonschema:: http://some.domain/with/a/path/spec.json\n\n\nDisplay a schema located in a file with an absolute path::\n\n .. jsonschema:: /home/leo/src/jsonschema/sample.json\n\nA path relative to the referencing document::\n\n .. jsonschema:: jsonschema/sample.json\n\nOr a schema defined in a Python object::\n\n .. jsonschema:: mod.pkg.SCHEMA\n\nWith all three of the above you may add JSON Pointer notation to display a subschema::\n\n .. jsonschema:: http://some.domain/with/a/path/spec.json#/path/to/schema\n .. jsonschema:: /home/leo/src/jsonschema/sample.json#/path/to/schema\n .. jsonschema:: jsonschema/sample.json#/path/to/schema\n .. jsonschema:: mod.pkg.SCHEMA#/path/to/schema\n\nAlternatively you can embed the schema::\n\n .. jsonschema::\n\n {\n \"$schema\": \"This field is ignored for now. Perhaps use it to indicate schema version in display?\",\n \"title\": \"Test data set 1: **Simple type**\",\n \"id\": \"http://this.better.be.a.regular.domain\",\n \"description\": \"These data sets exercise `JSON Schema `_ constructions and show how they are rendered.\\n\\nNote that it is possible to embed reStructuredText elements in strings.\",\n \"type\": \"string\",\n \"minLength\": 10,\n \"maxLength\": 100,\n \"pattern\": \"^[A-Z]+$\"\n }\n\nThis notation does not support JSON Pointer.\n\nJSON Schema extension\n=====================\n\n$$target\n sphinx-jsonschema extends JSON Schema with the ``$$target`` key.\n\n This key is only recognized at the outermost object of the schema.\n\nJSON Schema uses the ``$ref`` key in combination with the ``$id`` key to cross-reference between schemas.\n\nSphinx-jsonschema ignores ``$id`` but uses the value of ``$ref`` to create a reStructuredText ``:ref:`` role.\n\nFor this to work you need to mark the target schema with the ``$$target`` key, the value of which must be\nidentical to the value of the corresponding ``$ref`` key.\n\nSo a schema::\n\n {\n \"title\": \"Schema 1\",\n \"$ref\": \"#/definitions/schema2\"\n }\n\nwill have its ``$ref`` replaced by a link pointing to::\n\n {\n \"title\": \"Schema 2\",\n \"$$target\": \"#/definitions/schema2\"\n ...\n }\n\nOccasionally a schema will be addressed from several other schemas using different ``$ref`` values.\nIn that case the value of ``$$target`` should be a list enumerating all different references to the\nschema.\n\n$$description\n sphinx-jsonschema extends JSON Schema with the ``$$description`` key.\n\nThis key serves the same purpose as the ``description`` key and can be used in the same way.\nIt differs from ``description`` in that it allows an array of strings as value instead of a\nsingle string.\n\nThis allows you to write::\n\n {\n ...\n \"description\": \"+------------+------------+-----------+ \\n| Header 1 | Header 2 | Header 3 | \\n+============+============+===========+ \\n| body row 1 | column 2 | column 3 | \\n+------------+------------+-----------+ \\n| body row 2 | Cells may span columns.| \\n+------------+------------+-----------+ \\n| body row 3 | Cells may | - Cells | \\n+------------+ span rows. | - contain | \\n| body row 4 | | - blocks. | \\n+------------+------------+-----------+\",\n ...\n }\n\nas::\n\n {\n ...\n \"$$description\": [\n \"+------------+------------+-----------+\",\n \"| Header 1 | Header 2 | Header 3 |\",\n \"+============+============+===========+\",\n \"| body row 1 | column 2 | column 3 |\",\n \"+------------+------------+-----------+\",\n \"| body row 2 | Cells may span columns.|\",\n \"+------------+------------+-----------+\",\n \"| body row 3 | Cells may | - Cells |\",\n \"+------------+ span rows. | - contain |\",\n \"| body row 4 | | - blocks. |\",\n \"+------------+------------+-----------+\"\n ],\n ...\n }\n\nWhich clearly is much more readable and maintainable.\n\nLicence\n=======\n\nCopyright Leo Noordergraaf, All rights reserved.\n\nThis software is made available under the GPL v3.\n\n\nChangelog\n=========\n\nVersion 1.19.1\n\n`Eddie Darling ` with `Michal Čihař `\nand `Kim Berninger ` fixed a bug addressing relative files.\n\nVersion 1.19.0\n--------------\n\n`Glenn Nicholls ` contributed code to load a schema from a\nPython dict or object (or actually any Python entity with a ``__str__`` method.).\n\nVersion 1.18.0\n--------------\n\nExpanding on the work of `Pavel Odvody `_ with JSON Pointer\nthe ``:pass_unmodified:`` option is included.\nThis option prevents escaping the string pointed at.\nThis extension arose from discussions with `Ryan Lane `\n\nVersion 1.17.2\n--------------\n\n`Ezequiel Orbe `_ found, reported and fixed a bug escaping backspaces.\n\nVersion 1.17.0\n--------------\n\n`Pavel Odvody `_ contributed the ``:hide_key:`` directive option.\nThis option allows you to hide certain keys, specified by a JSON Path specification, to be excluded\nfrom rendering.\n\n\nVersion 1.16.11\n---------------\n\nRemoved debugging code left in, pointed out by `Kevin Landreth `.\n\nVersion 1.16.10\n---------------\n\n`iamdbychkov `_ added the ``:encoding:`` directive option.\nThis option allows explicit control of the encoding used to read a file\ninstead of relying on the operating system default.\n\nVersion 1.16.9\n--------------\n\nBugfix.\n\nVersion 1.16.8\n--------------\n\n`Jens Nielsen `_ improved rendering of string values.\n\nVersion 1.16.5-6\n----------------\n\nBugfix version.\n\nVersion 1.16.4\n--------------\n\nIntroduces the ``:lift_title:`` directive option suggested by `ankostis `_.\nAnkostis also provided an example on how to extend the formatter to handle custom properties.\n\nFixed a bug in rendering the ``items`` attribute of the ``array`` type reported by nijel (https://github.com/nijel).\n\nVersion 1.16.1-3\n----------------\n\nFixed bugs rendering the ``default`` and ``examples`` keywords.\n\nIntroduced the configuration entry ``jsonschema_options`` setting default values for the directive options\nintroduced in 1.16. The options now can accept a parameter to explicitly turn the option on or off.\n\nVersion 1.16\n------------\n\n`WouterTuinstra `_ reimplemented support for ``dependencies`` and properly this time.\nHe also improved error handling and reporting and added a couple of options improving the handling of references.\n\nThe most important additions are the directive options ``:lift_description:``, ``:lift_definitions:``,\n``:auto_target:`` and ``:auto_reference:``.\n\nIn addition to all that he also implemented support for the ``if``, ``then`` and ``else`` keywords.\n\nVersion 1.15\n------------\n\nAdd support for the ``dependencies`` key.\n\n\nVersions 1.12 and 1.13 and 1.14\n-------------------------------\n\nSolved several minor bugs.\n\n\nVersion 1.11\n------------\n\nSolved a divergence of the standard reported by bbasic (https://github.com/bbasics).\n\nVersion 1.10\n------------\n\n`Ivan Vysotskyy `_ contributed the idea to use an array with\nthe ``description`` key resulting in the new ``$$description`` key.\n\n\nVersion 1.9\n-----------\n\n`Tom Walter `_ contributed the ``example`` support.\n\nVersion 1.4\n-----------\n\n`Chris Holdgraf `_ contributed Python3 and yaml support.\n\nVersion 1.3\n-----------\n\nAdd unicode support.\n\nVersion 1.2\n-----------\n\nImproved formatting.\n\nVersion 1.1\n-----------\n\nImplemented schema cross referencing.\n\nVersion 1.0\n-----------\n\nInitial release of a functioning plugin.","description_content_type":"","docs_url":null,"download_url":"","downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://github.com/lnoor/sphinx-jsonschema","keywords":"sphinx json schema","license":"GPLv3","license_expression":null,"license_files":null,"maintainer":"","maintainer_email":"","name":"sphinx-jsonschema","package_url":"https://pypi.org/project/sphinx-jsonschema/","platform":"any","project_url":"https://pypi.org/project/sphinx-jsonschema/","project_urls":{"Homepage":"https://github.com/lnoor/sphinx-jsonschema"},"provides_extra":null,"release_url":"https://pypi.org/project/sphinx-jsonschema/1.19.1/","requires_dist":null,"requires_python":"","summary":"Sphinx extension to display JSON Schema","version":"1.19.1","yanked":false,"yanked_reason":null}

Package search

sphinx-jsonschema

project_urls

Dependencies

All package metadata

Releases