A data interchange format for Bible-centric content.
See https://docs.burrito.bible/ (or https://scripture-burrito.readthedocs.io/) for the documentation, this repo is the source files.
If you want to suggest a change, please fork this repo and create a PR, or create an Issue.
Install the sphinx engine
sudo apt-get install python-sphinx
pip install sphinx-jsonschema
Then run the build script from the docs/ directory.
NOTE: this top level makefile is just a shorcut to building the html.
make
The docs are written in reStructuredText, processed by Sphinx, and hosted online by Read the Docs.
See the reStructuredText Primer and the Docutils reStructuredText Directives documentation to learn how to use the syntax.
The specific schema documentation is generated from the schema itself using sphinx-jsonschema. Take special care to define the title
and description
attributes well as they will be the primary method of documentation for the specification. Also, wherever possible, include examples
as that aids in comprehension.
One special note, any section that needs to be linked to from another section should have a special $$target
attribute as well as a title
attribute for sphinx-jsonschema to work properly.
Also, note that there is a script which automatically takes the schema and creates the .rst
files for Sphinx to process. This should be done anytime changes are made to the schema (and should probably be part of the sphinx builder).
cd docs/docs/schema_docs
./gen_schema_docs.sh
There is both a Python and JavaScript utility included in code/
that validate JSON documents against the schema.
The Python script requires jsonschema
(run pip install jsonschema
) and may be run as follows:
python code/validate.py docs/examples/artifacts/*.json
The VS Code documentation explains how to setup VS Code for real time validation of JSON files using a schema.
In short, create a .vscode/settings.json
file in your scripture-burrito
working directory with the following:
{
"json.schemas": [
{
"fileMatch": [
"*.json"
],
"url": "file:///Users/jesse/vcs/scripture-burrito/schema/metadata.schema.json"
}
]
}
Of course, use the actual local path on your system for metadata.schema.json
.
To test, open up schema/scriptureText.json
and make something invalid, and see the result, like this: