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:

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:

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:

{
    "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:

.. 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``

Testing

Install the project along with its test dependencies using Poetry:

poetry install --with tests

Then run the test suite with pytest:

poetry run pytest --cov=jsonschema2rst --cov-report=term-missing tests jsonschema2rst

The project also uses pre-commit for linting and formatting checks (via ruff). To run all hooks against the whole codebase:

pre-commit run --all-files

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!