jsonschema2rst

jsonschema2rst ++++++++++++++

This project aims to parse JSON schemas or YAML schemas in order to create RestructuredText documentation. Using a tool like Sphinx, it is possible to create high readable documentation from the files generated, which are RST formatted text.

The outcome RST can be customized by defining a blacklist in csv and using a custom CSS file. that will inherit the Sphinx one. For the latter, an example is provided.

Usage

To create RST files from JSON schemas (or YAML) run the command:

.. code-block:: bash

jsonschema2rst input_folder output_folder

This command will take all JSON or YAML files in this path, sub-folders included, and wll create a new directory - removing it if already exists - where all parsed RST file will be placed.

Example

Let's assume you run the following command:

.. code-block:: bash

jsonschema2rst json_folder rst_output_folder

and also let's assume the folder json_folder contains the file url.json, which contains the following schema:

.. code-block::

{
    "title": "URL of related document",
    "properties": {
        "description": {
            "type": "string"
        },
        "value": {
            "format": "url",
            "type": "string"
        }
    },
    "type": "object"
}

As result, jsonschema2rst will create a file called url.rst in the rst_output_folder that will contain the following rst code:

.. code-block:: bash

.. contents:: Table of Contents
.. section-numbering::
.. container:: section-title
 url.json

.. container:: title

 URL of related document

**type** : ``object``

**Properties:** description_, value_


.. description:

description
+++++++++++

**type** : ``string``


.. value:

value
+++++


**type** : ``string``

**format** : ``url``

Extra

In case you want to generate HTML documentation using a tool like Sphinx, we suggest you to try the custom.css file in the contribution folder to make your schemas documentation looking better. What you need is just replace the default css used by Sphinx in the conf.py file with the one proposed, then enjoy!