Create sample data and stub data model documentation for Kasabi Datasets.

The code includes scripts to extract sample records from a dataset, formatting them as simple plain-text or HTML. HTML output can be templated so that the documentation can be standardized.

INSTALLATION

You'll need to be running Ruby 1.8.7 or higher and have installed the linkeddata, json and kasabi gems:

sudo gem install linkeddata json kasabi

The code uses the Kasabi SPARQL client library and assumes that you have an environment variable set with your Kasabi API Key:

export KASABI_API_KEY=abcdef...

USAGE

Extract examples:

ruby bin/examples.rb examples/bricklink.json

Generate HTML docs:

ruby bin/docs.rb examples/bricklink.json template/template.erb

The HTML template is an ERB template. See the provided template for an idea of what data is exposed.

Probe endpoint for list of types and generate stub configuration:

ruby bin/probe.rb http://api.kasabi.com/api/an-endpoint

The output is a basic stub JSON file that can be tweaked to generate docs and examples for specific types, as well as including prefixes.

CONFIGURATION

The docs and examples scripts use a JSON file as configuration:

 {
   "types": {
    "Minifig": "http://data.kasabi.com/dataset/bricklink/schema/Minifig",
    "Catalog": "http://data.kasabi.com/dataset/bricklink/schema/Catalog",
    "Set": "http://data.kasabi.com/dataset/bricklink/schema/Set"
   },
   "endpoint": "http://api.kasabi.com/api/sparql-endpoint-bricklink",
   "prefixes": {
     "brick": "http://data.kasabi.com/dataset/bricklink/schema/"
   }
 }

The configuration file should identify the Kasabi SPARQL Endpoint, prefixes to be used to generate tidy output, and the types for which examples or documentation should be generated.

The code could be greatly improved in a number of ways, e.g.:

• Use prefix.cc as a default list of JSON prefixes
• Fetching schemas to provide better default class and property names
• Other improvements to the default templated output

This would all make better use of cues in the data as well as community resources.

However it is intentional that documentation isn't generated by default for all types: the desire is to provide documentation for the key resources in a dataset, to provide a developer with insights on the important entities and their relationships. Simply generating documentation for everything doesn't always achieve that. This is also why a schema diagram isn't generated automatically, as they're rarely as useful/readable as something that is hand-crafted.

Obviously these facilities could be added, but this was a "good enough" hack to support development of some initial stub documentation for a large number of different datasets. Contributions welcome!