Auto documentation #348
Auto documentation #348
Conversation
|
This problem with python-jsonschema-objects is being seen elsewhere, too. See issue cwacek/python-jsonschema-objects#223. This is because the python-jsonschema-objects is using a module from the jsonschema library that was intended to be private, which was recently removed in the release to jsonschema 4.0.0. The maintainers of jsonschema have no intention of restoring or preserving the private module (see statement here), and the python-jsonschema-objects issue tracker has me doubtful that this will be addressed quickly. |
|
8c8ff8e addresses the testing issue by locking the version of jsonschema used. This is a crappy solution but the best we can do until python-jsonschema-objects maintainers address the issue. We should consider doing the same over at ga4gh/vrs-python. |
|
Moving this PR to draft status. RTD isn't building the docs properly (see RTD Allele section from this branch), need to investigate. |
schema/vrs.json
Outdated
| @@ -21,7 +21,7 @@ | |||
| } | |||
| }, | |||
| "MolecularVariation": { | |||
| "description": "A variation on a contiguous molecule.", | |||
| "description": "A :ref:`variation` on a contiguous molecule.", | |||
There was a problem hiding this comment.
@ahwagner while i think this is cool. I'm just wondering how description and other attribute string values that contain RST tags will impact other tools that use these fields to display the schema documentation (i.e. swagger). I may be missing the mark here and it really may not be a big deal, but are we thinking about how other commonly used tools will work with our enhanced RestructuredText syntax. I suppose the big value of RST and markdown in general is that it is still very legible even in an unrendered state.
There was a problem hiding this comment.
I think this is good feedback, will address.
| @@ -70,24 +79,30 @@ definitions: | |||
|
|
|||
| Allele: | |||
| description: >- | |||
| The sequence state at a Location. | |||
| The state of a molecule at a :ref:`Location`. | |||
There was a problem hiding this comment.
Interesting that you used the term molecule instead of sequence here. Wouldn't sequence be more concise?
There was a problem hiding this comment.
This change was made to align the YAML with the documentation. But molecule probably is better anyways, as it also covers ChromosomeLocation.
|
@ahwagner: I was in the middle of reviewing the yaml tools PR when it merged. I have some concerns and questions. These changes seem big enough that they merited discussion before merging. We definitely should not be putting RST in jsonschema. Markdown is supported (specifically by openapi clients), but RST isn't. I also don't understand the rationale for the heritable business or how it's implemented. However, it appears to make schema.yaml no longer jsonschema. If true, I want to reconsider that as well. |
| @@ -400,7 +414,7 @@ | |||
| ] | |||
| }, | |||
| "SequenceInterval": { | |||
| "description": "A SequenceInterval represents a span of sequence. Positions are always represented by contiguous spans using interbase coordinates.\nSequenceInterval is intended to be compatible with that in Sequence Ontology ([SO:0000001](http://www.sequenceontology.org/browser/current_svn/term/SO:0000001)), with the exception that the GA4GH VRS SequenceInterval may be zero-width. The SO definition is for an \"extent greater than zero\".", | |||
| "description": "A SequenceInterval represents a span of sequence. Positions are always represented by contiguous spans using interbase coordinates. SequenceInterval is intended to be compatible with that in Sequence Ontology (SO:0000001), with the exception that the GA4GH VRS SequenceInterval may be zero-width. The SO definition is for an \"extent greater than zero\".", | |||
There was a problem hiding this comment.
@ahwagner let's add links back in (markdown style) to the JSON-Schema artifact
This PR adds auto-documentation functionality, class inheritance, and namespaced references to the YAML syntax.
Tests are passing locally on Python 3.9.4. There appears to be some error in
python_jsonschema_objectsthat will need to be resolved. @reece any thoughts on that?