Schema doesn't get built unless there is something after it

[isaacgsmith]

I was trying to include a schema (written in YAML) in my documentation (built with Sphinx), but it did not work unless there was something under the jsonschema directive.

For example, if I put in my RST file:

.. jsonschema:: example1.yml

.. jsonschema:: example2.yml

only example1 would build. If the document ended with .. jsonschema:: example1.yml, it would not build, but if it was

.. jsonschema:: example1.yml

example text

it would build.

If this is not just a problem on my end, this may be something you want to fix or document.

[lnoor]

The only way I could reproduce this is when the yaml file has errors in it. Could you verify the correctness of your yaml file and let me know the result.

sphinx-jsonschema will try to read a file using pyyaml. When this fails it silently falls back to json.

I did notice something that could be an issue: sphinx-jsonschema silently converts \\( and \\) character sequences to \\\\( and \\\\); this is probably an error.

Does your yaml file contain sequences like \\( or \\)? If so, do you get output when you (temporarily) remove these sequences?

[isaacgsmith]

I'm so sorry for the extremely late response. Here is an example file for which this problem occurred:

number: 1
additionalProperties: false
properties:
  property1:
    type: string
    default: "property1"
    description: A string
  property2:
    type: boolean
    default: false
    description: True or False

[lnoor]

No problem. Still I cannot replicate the problem. With your yaml from above in ex.yml and this index.rst:

Contents:

.. toctree::
    :maxdepth: 2


yaml test
=========

.. jsonschema:: ex.yml

and a nearly empty conf.py including nothing but sphinx-jsonschema I get perfectly good output.

Please send me a complete example demonstrating the problem. If you have a stand-alone example containing at least your conf.py, yaml and index.rst please send those files to me. Even better if possible: create a venv in which the problem is demonstrated and send me the enire venv as a tar.gz. You'll find my email address in the git log.

I'd really like to know what is happening but I need to be able to replicate this.

[isaacgsmith]

Hi,

It took me a bit to replicate the problem starting from scratch. It turns out, my project uses sphinx-astropy which appears to be causing the problem. This may not be a problem you can or want to address, but in case, I will be sending an example via email.

[raspe88]

I have the same issue and found a workaround:

It is enough to add a comment at the end, such as

.. This comment is needed because of https://github.com/lnoor/sphinx-jsonschema/issues/60

[lnoor]

I assume you are not using the sphinx-astropy extension? That would mean that the problem is not with that extension.

Can you produce a small sample that illustrates the problem on the current version? That would be really useful. I may have a blind spot for it but none of the things i tried produced this problem.

[raspe88]

I'm still trying to construct a minimal example that can reproduce the error but it is difficult. sphinx-astropy is not used.

[lnoor]

So sorry. I failed trying to reproduce this problem. I suppose you cannot share the schema that is showing this problem?

[spagh-eddie]

@raspe88 @lnoor I have been able to reproduce this issue. Here is an MRE!

issue

It seems that the epilog is not playing nicely with jsonschema directives at the end of the file.

The following are workarounds:

• remove the epilog from conf.py
• have anything below the directive, such as:
  • :lift_description:
  • or text
  • or a comment

pdb on the first directive

(Pdb) p source
'/Users/.../Desktop/spagh-eddie/test/source/../a.json'
(Pdb) p self.state.document.current_source
'/Users/.../Desktop/spagh-eddie/test/source/index.rst'
(Pdb) continue

pdb on the second directive

(Pdb) p source
'../a.json'
(Pdb) p self.state.document.current_source
'<rst_epilog>'

to reproduce

% tree
.
├── a.json
└── source
    ├── conf.py
    └── index.rst

# conf.py

extensions = ["sphinx-jsonschema"]
rst_epilog = """
.. |epilog| replace:: :strong:`EPILOG`
"""
keep_warnings = True

.. 
    index.rst

My |epilog| contains replacements.

.. jsonschema:: ../a.json

.. jsonschema:: ../a.json