Metadata-Version: 2.4
Name: jsonschema2rst
Version: 0.1.8
Summary: Parser for yaml/json schemas to rst
License-Expression: GPL-2.0-or-later
License-File: LICENSE.txt
Keywords: jsonschema,yaml,rst,parser,documentation
Author: CERN
Author-email: admin@inspirehep.net
Requires-Python: >=3.11,<4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: pyyaml (>=6.0,<7.0)
Project-URL: Homepage, https://github.com/inspirehep/jsonschema2rst
Description-Content-Type: text/markdown

# 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:

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

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

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

```rst
.. 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](https://python-poetry.org/):

```bash
poetry install --with tests
```

Then run the test suite with pytest:

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

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

```bash
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!

