Generating HTML documentation of OWL

In response to http://www.w3.org/2011/prov/track/issues/270

We want something "javadoc"-ish, like:

• http://open-biomed.sourceforge.net/opmv/ns.html
• http://xmlns.com/foaf/spec/
• http://rdfs.org/sioc/spec/

From the editors

SIOC

From SIOCer John Breslin:

https://github.com/zazi/specgen by Bob Ferris (Older https://bitbucket.org/wikier/specgen/wiki/Home)

• Stian: I tried using specgen, and one of the problems is that there are so many forks. I tried https://github.com/zazi/specgen which only outputted 3 properties or so from our OWL. The other forks seemed to fail in various ways, but I did not have time to try it properly.
• WebID XG extension of specgen: http://dvcs.w3.org/hg/WebID/file/029f115c08a5/ontologies/specgen

From Uldis:

This is the original SpecGen4 tool used to generate the SIOC Specification: http://sw.deri.org/svn/sw/2005/08/sioc/ontology/spec/

• home page: http://sioc-project.org/specgen

If you check out the code and run it (see example script "sioc"), it should generate the SIOC spec.

Besides newer SpecGen versions (John pointed to these) there's also:

• http://moustaki.org/ontospec/ - used for the Music ontology
• http://www.co-ode.org/downloads/owldoc/

One thing you have to be careful about if expressing the specification directly in HTML+RDFa (and generating RDF/XML from that): it is possible to create RDFa documents where the human readable text does not match RDFa statements. - e.g., if one copy-pastes an HTML snippet to create a new class or property, changes the name visible in HTML but forgets to update the URI.

FOAF

From danbri:

FOAF's spec is generated from index.rdf schema input plus a directory full of per-term snippets, and an HTML template. The tool is a rather messy Python (previously Ruby) thing called specgen, source is at http://svn.foaf-project.org/foaftown/specgen/README.TXT

You can find the raw files for FOAF nearby in Subversion repo at http://svn.foaf-project.org/foaf/trunk/xmlns.com/htdocs/

It's not the most sophisticated ontology documentation tool around, but it kinda sorta works. It could do with re-writing, but we've never really got clear on the requirements. Perhaps the spec should be maintained in HTML+RDFa, for example, with the RDF/XML view (and internal cross-links, annotations etc) mechnically generated?

I like that our html output explains domain/range like this,

'Domain: having this property implies being a Person Range: every value of this property is a Thing'

OPMV

http://trdf.sourceforge.net/provenance/ns.html

BTW, the cool thing about the OPMV documentation (as well as the Provenance
Vocabulary documentation [1] which served as a template for the OPMV doc) is,
that it embeds the whole vocabulary definition as RDFa in the HTML. Actually,
for Provenance Vocabulary it's the main representation from which we generate
representations in other formats such as RDF/XML. However, creating the HTML
(and the embedded RDFa) was a manual effort.

semweb/lod list

Yes, see TopBraid Composer, http://topquadrant.com/. Any model can be exported to a set of HTML files wit class and property browsers.

http://answers.semanticweb.com/questions/1087/generating-documentation-from-rdfs-andor-owl-vocabularies

http://ontorule-project.eu/parrot/parrot (PROV-O in parrot)

Dave Wood:

• OWLDoc: http://www.co-ode.org/downloads/owldoc/
• SpecGen: https://github.com/zazi/specgen

John Erickson:

• jOWL <http://jowl.ontologyonline.org/documentation.html>: a javascript library that loads and visualizes OWL-DL documents
• vocdoc.rb (aka RDoc) <http://kantenwerk.org/voc_doc/doc/>: creates simple latex and html documentation for a given OWL ontology file (in Turtle)

• source code to https://scm.escience.rpi.edu/svn/public/demos/owlmobile/ NB: this hasn't been updated since 2008, so it doesn't support OWL2 constructs. Evan Patton

OOR list

• Altova's Semantic architect to auto generate HTML and other documentation for RDFS and OWL ontologies

SPECGen Version 6

http://smiy.wordpress.com/2010/07/13/my-specgen-version-6/

Protege list

Joshua Taylor: Have you had a look at OWLDoc? http://code.google.com/p/co-ode-owl-plugins/wiki/OWLDoc The resulting documentation has IMO, a more javadoc-ish feel to it than those examples, though I'm not sure what you can get in terms of free form prose aside from what you put in with rdf annotations.

prov-wg

• http://www.essepuntato.it/lode suggested by Jun
  • PROV-O using the previous service: http://www.essepuntato.it/lode/owlapi/http://dvcs.w3.org/hg/prov/raw-file/tip/ontology/ProvenanceOntology.owl. Some parts look really useful to what we want to do.

PROV-O Views in the previous tools

Note: jOWL browser uses a javascript library (jOWL) that makes it easy to load the ontology, properties, etc. We should have a look at it.