.. sphinx-jsonschema README
Copyright: (C) 2017-2020, Leo Noordergraaf
=================
sphinx-jsonschema
=================
This package contains sphinx-jsonschema, an extension to Sphinx to allow
authors to display a `JSON Schema <http://json-schema.org>`_ in their
documentation.
A dockerized version can be found at: `Extended Sphinx <https://hub.docker.com/r/lnoor/sphinx-extended>`_.
It arose out of a personal itch and implements what I needed.
Some features of JSON Schema are (not yet) implemented.
Also I can imagine that other display layouts are desired.
Let me know in comments and perhaps pull requests.
Features
========
* Near complete support for all features of JSON Schema Draft 4.
* Supports inline schemas as well as external schemas loaded from a file or URL.
* Supports JSON Pointer notation on external resources to select a subschema.
* Supports cross references between schemas.
* Allows reStructuredText markup in ``title`` and ``description`` fields.
* Allows JSON Schema definitions in both JSON and YAML format.
* Supports the ``examples`` keyword from Draft 7.
Installation
============
Install the package using pip::
pip install sphinx-jsonschema
and add it to the extensions list in your conf.py::
extensions = [
'sphinx-jsonschema'
]
Usage
=====
The extension adds a single directive to Sphinx: **jsonschema**.
You provide it with either an http URL to a schema or you may
embed the schema inline.
Example
=======
Display a schema fetched from a website::
.. jsonschema:: http://some.domain/with/a/path/spec.json
Display a schema located in a file with an absolute path::
.. jsonschema:: /home/leo/src/jsonschema/sample.json
A path relative to the referencing document::
.. jsonschema:: jsonschema/sample.json
Or a schema defined in a Python object::
.. jsonschema:: mod.pkg.SCHEMA
With all three of the above you may add JSON Pointer notation to display a subschema::
.. jsonschema:: http://some.domain/with/a/path/spec.json#/path/to/schema
.. jsonschema:: /home/leo/src/jsonschema/sample.json#/path/to/schema
.. jsonschema:: jsonschema/sample.json#/path/to/schema
.. jsonschema:: mod.pkg.SCHEMA#/path/to/schema
Alternatively you can embed the schema::
.. jsonschema::
{
"$schema": "This field is ignored for now. Perhaps use it to indicate schema version in display?",
"title": "Test data set 1: **Simple type**",
"id": "http://this.better.be.a.regular.domain",
"description": "These data sets exercise `JSON Schema <http://json-schema.org>`_ constructions and show how they are rendered.\n\nNote that it is possible to embed reStructuredText elements in strings.",
"type": "string",
"minLength": 10,
"maxLength": 100,
"pattern": "^[A-Z]+$"
}
This notation does not support JSON Pointer.
JSON Schema extension
=====================
$$target
sphinx-jsonschema extends JSON Schema with the ``$$target`` key.
This key is only recognized at the outermost object of the schema.
JSON Schema uses the ``$ref`` key in combination with the ``$id`` key to cross-reference between schemas.
Sphinx-jsonschema ignores ``$id`` but uses the value of ``$ref`` to create a reStructuredText ``:ref:`` role.
For this to work you need to mark the target schema with the ``$$target`` key, the value of which must be
identical to the value of the corresponding ``$ref`` key.
So a schema::
{
"title": "Schema 1",
"$ref": "#/definitions/schema2"
}
will have its ``$ref`` replaced by a link pointing to::
{
"title": "Schema 2",
"$$target": "#/definitions/schema2"
...
}
Occasionally a schema will be addressed from several other schemas using different ``$ref`` values.
In that case the value of ``$$target`` should be a list enumerating all different references to the
schema.
$$description
sphinx-jsonschema extends JSON Schema with the ``$$description`` key.
This key serves the same purpose as the ``description`` key and can be used in the same way.
It differs from ``description`` in that it allows an array of strings as value instead of a
single string.
This allows you to write::
{
...
"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+------------+------------+-----------+",
...
}
as::
{
...
"$$description": [
"+------------+------------+-----------+",
"| Header 1 | Header 2 | Header 3 |",
"+============+============+===========+",
"| body row 1 | column 2 | column 3 |",
"+------------+------------+-----------+",
"| body row 2 | Cells may span columns.|",
"+------------+------------+-----------+",
"| body row 3 | Cells may | - Cells |",
"+------------+ span rows. | - contain |",
"| body row 4 | | - blocks. |",
"+------------+------------+-----------+"
],
...
}
Which clearly is much more readable and maintainable.
Licence
=======
Copyright Leo Noordergraaf, All rights reserved.
This software is made available under the GPL v3.
Changelog
=========
Version 1.19.1
`Eddie Darling <https://github.com/spagh-eddie>` with `Michal Čihař <https://github.com/nijel>`
and `Kim Berninger <https://github.com/kimberninger>` fixed a bug addressing relative files.
Version 1.19.0
--------------
`Glenn Nicholls <https://github.com/GlenNicholls>` contributed code to load a schema from a
Python dict or object (or actually any Python entity with a ``__str__`` method.).
Version 1.18.0
--------------
Expanding on the work of `Pavel Odvody <https://github.com/shaded-enmity>`_ with JSON Pointer
the ``:pass_unmodified:`` option is included.
This option prevents escaping the string pointed at.
This extension arose from discussions with `Ryan Lane <https://github.com/ryan-lane>`
Version 1.17.2
--------------
`Ezequiel Orbe <https://github.com/eorbe>`_ found, reported and fixed a bug escaping backspaces.
Version 1.17.0
--------------
`Pavel Odvody <https://github.com/shaded-enmity>`_ contributed the ``:hide_key:`` directive option.
This option allows you to hide certain keys, specified by a JSON Path specification, to be excluded
from rendering.
Version 1.16.11
---------------
Removed debugging code left in, pointed out by `Kevin Landreth <https://github.com/CrackerJackMack>`.
Version 1.16.10
---------------
`iamdbychkov <https://github.com/iamdbychkov>`_ added the ``:encoding:`` directive option.
This option allows explicit control of the encoding used to read a file
instead of relying on the operating system default.
Version 1.16.9
--------------
Bugfix.
Version 1.16.8
--------------
`Jens Nielsen <https://github.com/jenshnielsen>`_ improved rendering of string values.
Version 1.16.5-6
----------------
Bugfix version.
Version 1.16.4
--------------
Introduces the ``:lift_title:`` directive option suggested by `ankostis <https://github.com/ankostis>`_.
Ankostis also provided an example on how to extend the formatter to handle custom properties.
Fixed a bug in rendering the ``items`` attribute of the ``array`` type reported by nijel (https://github.com/nijel).
Version 1.16.1-3
----------------
Fixed bugs rendering the ``default`` and ``examples`` keywords.
Introduced the configuration entry ``jsonschema_options`` setting default values for the directive options
introduced in 1.16. The options now can accept a parameter to explicitly turn the option on or off.
Version 1.16
------------
`WouterTuinstra <https://github.com/WouterTuinstra>`_ reimplemented support for ``dependencies`` and properly this time.
He also improved error handling and reporting and added a couple of options improving the handling of references.
The most important additions are the directive options ``:lift_description:``, ``:lift_definitions:``,
``:auto_target:`` and ``:auto_reference:``.
In addition to all that he also implemented support for the ``if``, ``then`` and ``else`` keywords.
Version 1.15
------------
Add support for the ``dependencies`` key.
Versions 1.12 and 1.13 and 1.14
-------------------------------
Solved several minor bugs.
Version 1.11
------------
Solved a divergence of the standard reported by bbasic (https://github.com/bbasics).
Version 1.10
------------
`Ivan Vysotskyy <https://github.com/ivysotskyi>`_ contributed the idea to use an array with
the ``description`` key resulting in the new ``$$description`` key.
Version 1.9
-----------
`Tom Walter <https://github.com/EvilPuppetMaster>`_ contributed the ``example`` support.
Version 1.4
-----------
`Chris Holdgraf <https://github.com/choldgraf>`_ contributed Python3 and yaml support.
Version 1.3
-----------
Add unicode support.
Version 1.2
-----------
Improved formatting.
Version 1.1
-----------
Implemented schema cross referencing.
Version 1.0
-----------
Initial release of a functioning plugin.
Raw data
{
"_id": null,
"home_page": "https://github.com/lnoor/sphinx-jsonschema",
"name": "sphinx-jsonschema",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "sphinx json schema",
"author": "Leo Noordergraaf",
"author_email": "leo@noordergraaf.net",
"download_url": "https://files.pythonhosted.org/packages/9c/3f/559d054f977596c5535edfeeab1f3a278f3bbb81bada2a1cb3cadbf7bb67/sphinx-jsonschema-1.19.1.tar.gz",
"platform": "any",
"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 <http://json-schema.org>`_ in their\ndocumentation.\n\nA dockerized version can be found at: `Extended Sphinx <https://hub.docker.com/r/lnoor/sphinx-extended>`_.\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 <http://json-schema.org>`_ 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 <https://github.com/spagh-eddie>` with `Michal \u010ciha\u0159 <https://github.com/nijel>`\nand `Kim Berninger <https://github.com/kimberninger>` fixed a bug addressing relative files.\n\nVersion 1.19.0\n--------------\n\n`Glenn Nicholls <https://github.com/GlenNicholls>` 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 <https://github.com/shaded-enmity>`_ 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 <https://github.com/ryan-lane>`\n\nVersion 1.17.2\n--------------\n\n`Ezequiel Orbe <https://github.com/eorbe>`_ found, reported and fixed a bug escaping backspaces.\n\nVersion 1.17.0\n--------------\n\n`Pavel Odvody <https://github.com/shaded-enmity>`_ 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 <https://github.com/CrackerJackMack>`.\n\nVersion 1.16.10\n---------------\n\n`iamdbychkov <https://github.com/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 <https://github.com/jenshnielsen>`_ 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 <https://github.com/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 <https://github.com/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 <https://github.com/ivysotskyi>`_ 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 <https://github.com/EvilPuppetMaster>`_ contributed the ``example`` support.\n\nVersion 1.4\n-----------\n\n`Chris Holdgraf <https://github.com/choldgraf>`_ 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.",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Sphinx extension to display JSON Schema",
"version": "1.19.1",
"split_keywords": [
"sphinx",
"json",
"schema"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d0632ade4ea531188d23066308d6ae48",
"sha256": "b2385fe1c7acf2e759152aefed0cb17c920645b2a75c9934000c9c528e7d53c1"
},
"downloads": -1,
"filename": "sphinx-jsonschema-1.19.1.tar.gz",
"has_sig": false,
"md5_digest": "d0632ade4ea531188d23066308d6ae48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18599,
"upload_time": "2022-05-01T12:42:58",
"upload_time_iso_8601": "2022-05-01T12:42:58.089198Z",
"url": "https://files.pythonhosted.org/packages/9c/3f/559d054f977596c5535edfeeab1f3a278f3bbb81bada2a1cb3cadbf7bb67/sphinx-jsonschema-1.19.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-05-01 12:42:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "lnoor",
"github_project": "sphinx-jsonschema",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "sphinx-jsonschema"
}
JSON
