Add parameter for max depth

[ArtFlag]

Hello and thanks for this cool extension :)

How difficult would it be to add a parameter to choose how deep we want to read the schema?

Typically:

.. json-schema:: myfile.json
   :depth: 2

Thanks!

[lnoor]

Hi, very glad you like it!

It wouldn't be too hard to implement.
The _dispatch method in wide_format.py is the main entry point for the mutually recursive routines.
It already contains a nesting counter.
If you skip the body of it when the nesting depth is reached you're mostly done.
You may want to provide an indication that something was left out though.

However, depending on your needs, you might be better off using references to cap nesting.
Using separate files that refer to each other using $ref and $$target you don't need deep nesting but instead have parts of your schema hyperlinked.

Excerpt from one of my own schemas:

File product.json contains:

{
    "id": "<url referencing this file, required to make $ref use relative addressing>",
    "type": "object",
    "properties": {
        "startdate": {"$ref": "../shared/types.json/#date"},
        "enddate": {"$ref": "../shared/types.json/#date"},
        "supplier_startdate": {"$ref": "../shared/types.json/#nulleddate"},
        "supplier_enddate": {"$ref": "../shared/types.json/#nulleddate"}
    }
}

and types.json contains:

{
    "date": {
        "title": "Date",
        "$$target": ["#/date", "../shared/types.json/#date"],
        "description": "Date in international format YYYY-MM-DD",
        "type": "string",
        "pattern": "^[1-9][0-9]{3}-[01][0-9]-[0-3][0-9]$"
    },
    "nulleddate": {
        "title": "Optional date",
        "$$target": "../shared/types.json/#nulleddate",
        "description": "Optional date in international format YYYY-MM-DD",
        "oneOf": [
            {"$ref": "#/date"},
            {"type": "null"}
        ]
    }
}

I display product.json in a page detailing the product API and have a second page called "Types"
in which types.json is displayed.

Note the use of "$$target". Its contents should match exactly the corresponding $ref.
And since "date" is referenced from two different locations with two different "$ref" strings its
$$target is an array enumerating all those refs.

Hopes this helps to solve you issue.
If you still want to cap the recursion then by all means do and create a pull request for it.

regards,
Leo

[ArtFlag]

Hi Leo,

Thanks for the details, very useful!

I'm getting back to you super late about this. I've been digging in the Sphinx docs to understand how to quickly add a parameter to a directive without success.

I'm not sure if I'll have time to noodle with Sphinx and understand by trial and error what should be clearly explained in the docs! 😢 Ironic for a documentation platform 😄

[lnoor]

Hi Arthur,

It is in fact quite simple to have parameters on a directive.
I've included (and later dropped) a parameter in this package.
Check out e7ab0ef and look at the __init__.py code.
There you'll find code for the option display_if, that should get you going.

I can only wholeheartedly agree with your closing remark. It took a lot of time with a
debugger and experimentation to get this module to where it is now.
In all fairness though it is mostly docutils that lacks proper documentation, compared to that Sphinx is rather well documented.

Please let me know if you need further pointers and I will gladly accept a pull request for this feature.

[lnoor]

Oops, accidently closed.