Switch to sphinx-jsonschema

[jag3773]

Follow up to #111, working on #71 still.

You can now see what these pages look like at:

• https://docs.burrito.bible/en/sphinx-jsonschema_example/metadata_languages.html
• https://docs.burrito.bible/en/sphinx-jsonschema_example/metadata_common.html

For discussion, I'll paste my question from #111 here:

It's only possible to link to a top level schema file, not a specific definition therein. So the three links in langauge.schema.json only point to the top of the Common page. I think it would be valuable if we could layout the connections in such a way that we could link directly to the field being referenced. Brief documentation for how this works is at https://pypi.org/project/sphinx-jsonschema/.

[rdb]

What are you asking me to review here—the addition to requirements.txt or the generated documentation?

I personally am not a big fan of the table format. I'm having trouble visually parsing the result, especially of the language schema, with the references. I also think that if we can't link to a specific definition, that would be a shame. But, it does fulfill the basic requirement of listing and annotating the fields from our schema, so in that sense it's certainly better than including the JSON schemas verbatim.

[jag3773]

(This PR got split between #111 and #112 as I was trying to get RTD to process the build so that a visual inspection could be made. Hence, I'm not looking for a requirements.txt review 😄 )

I am interested in your feedback on the approach and the output. I was also a bit leery of the tabular output. It has the advantage of showing the hierarchy but it does seem difficult to read.

If we can figure out how to link at a more granular that would help, supposedly it's possible but I haven't figured it out yet.

I'm certainly interested in other opinions on the visual output as well. Is it helpful? We could try to modify the table CSS to get something easier to read or we could try another processor altogether.

[jag3773]

I've just updated the linking today to provide a more robust example. Now, notice that the links on https://docs.burrito.bible/en/sphinx-jsonschema_example/metadata_languages.html point to the following schema sections which get pulled in automatically from common.

Note that we can have those sections on the actually metadata_common page also, so that links from the languages page would hop over to common.

Again, looking for feedback on the overall idea of using sphinx-jsonschema to pull in documentation directly from the schema.