WIzard for DOCumenting Ontologies (WIDOCO)

WIDOCO helps you to publish and create an enriched and customized documentation of your ontology automatically, by following a series of steps in a GUI.

Author: Daniel Garijo Verdejo (@dgarijo)

Contributors: María Poveda, Idafen Santana, Almudena Ruiz, Miguel Angel García, Oscar Corcho, Daniel Vila, Sergio Barrio, Martin Scharm, Maxime Lefrancois, Alfredo Serafini, @kartgk, Pat Mc Bennett, Christophe Camel, Jacobus Geluk, Martin Scharm, @rpietzsch, Jonathan Leitschuh, Jodi Schneider, Giacomo Lanza, Alejandra Gonzalez-Beltran, Mario Scrocca, Miguel Angel García, Flores Bakker, @JohnnyMoonlight, René Fritze, @telecsur, Jan Vlug, Han Kruiger, Johannes Theissen-Lipp, Roberto Polli, Victor Chavez, Sirko Schindler and Michaël Dierick.

Citing WIDOCO: If you used WIDOCO in your work, please cite the ISWC 2017 paper: https://iswc2017.semanticweb.org/paper-138

@inproceedings{garijo2017widoco,
  title={WIDOCO: a wizard for documenting ontologies},
  author={Garijo, Daniel},
  booktitle={International Semantic Web Conference},
  pages={94--102},
  year={2017},
  organization={Springer, Cham},
  doi = {10.1007/978-3-319-68204-4_9},
  funding = {USNSF ICER-1541029, NIH 1R01GM117097-01},
  url={http://dgarijo.com/papers/widoco-iswc2017.pdf}
}

If you want to cite the latest version of the software, you can do so by using: https://zenodo.org/badge/latestdoi/11427075.

Downloading the executable

To download WIDOCO, you need to download a JAR executable file. Check the latest release for more details: (https://github.com/dgarijo/WIDOCO/releases/latest).

Importing WIDOCO as a dependency

Just add the dependency and repository to your pom.xml file as follows. See the WIDOCO JitPack page to find alternative means to incorporate WIDOCO to your project.

<dependencies>
  <dependency>
      <groupId>com.github.dgarijo</groupId>
      <artifactId>Widoco</artifactId>
      <version>v1.4.24</version>
  </dependency>
</dependencies>

[ ... ]

<repositories>
	<repository>
	    <id>jitpack.io</id>
	    <url>https://jitpack.io</url>
	</repository>
</repositories>

Description

WIDOCO helps you to publish and create an enriched and customized documentation of your ontology, by following a series of steps in a wizard. We extend the LODE framework by Silvio Peroni to describe the classes, properties and data properties of the ontology, the OOPS! webservice by María Poveda to print an evaluation and the Licensius service by Victor Rodriguez Doncel to determine the license URI and title being used. In addition, we use WebVowl to visualize the ontology and have extended Bubastis to show a complete changelog between different versions of your ontology.

Features of WIDOCO:

• Automatic documentation of the terms in your ontology (based on LODE). Now you can use Markdown on your class descriptions (see example)
• Massive metadata extraction and support: WIDOCO will enhance your ontology documentation based on your ontology annotations. Now you can add custom logos and images, edit the content of your sections, etc. by just editing metadata. See our supported metadata and recommendations for more information.
• Automatic annotation in JSON-LD snippets of the html produced.
• Association of a provenance page which includes the history of your vocabulary (W3C PROV-O compliant).
• Guidelines on the main sections that your document should have and how to complete them.
• Integration with diagram creators (WebVOWL).
• Automatic changelog of differences between the actual and the previous version of the ontology (based on Bubastis).
• Separation of the sections of your html page so you can write them independently and replace only those needed.
• Content negotiation and serialization of your ontology according to W3C best practices
• Evaluation reports of your ontology (using the OOPS! web service)
• Integration with license metadata services (Licensius) to automatically describe the license used in your ontology.

Examples

Examples of the features of WIDOCO can be seen on the gallery

GUI Tutorial

A tutorial explaining the main features of the GUI can be found here

Metadata usage

To see how WIDOCO recognizes metadata annotations in your ontology to create the documentation files, see the WIDOCO metadata documentation. To learn which metadata properties we recommend adding to your ontology for producing a nice-looking documentation, have a look at our best practices guide.

For example, in order to show your logo in your documentation you just need to use foaf:logo as an annotation, as follows:

@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
<https://w3id.org/roar> a owl:Ontology ;
    foaf:logo <https://www.leonvanwissen.nl/vocab/roar/docs/resources/roar-logo.png#> .

and it will show right next to the title. The WIDOCO metadata documentation shows all supported metadata fields.

How to use WIDOCO

Building the JAR executable

We provide JAR files for each release (see the releases page). However, if you want to build WIDOCO from scratch, just cd into the project folder and run:

mvn install

The JAR will be generated in a "JAR" folder. The name will follow the pattern: widoco-{VERSION_ID}-jar-with-dependencies.jar, where {VERSION_ID} is the version number of the tool.

JAR execution

Download the latest .jar WIDOCO available release (it will be something like widoco-VERSION-jar-with-dependencies.jar). Then just double click the .jar file.

You may also execute WIDOCO through the command line. Usage:

java -jar widoco-VERSION-jar-with-dependencies.jar [OPTIONS]

Docker execution

If you don't want to use the JAR directly, you may run the project using a Docker container. First you will need to download or build the image, and then run it.

Reusing a pre-existing image

We build containers in the GitHub image registry for all latest releases. In order to import one, just run the following command, stating the version of Widoco you prefer (e.g., for v1.4.23):

docker pull ghcr.io/dgarijo/widoco:v1.4.23

To browse all available images, see the GitHub image registry.

Building the image yourself

Build the image using the Dockerfile in project folder:

docker build -t dgarijo/widoco .

Running WIDOCO's image

You can now execute WIDOCO through the command line. Usage:

docker run -ti --rm dgarijo/widoco [OPTIONS]

Note: If you downloaded the image from the GitHub registry, you will have to change dgarijo/widoco with the name of the image you downloaded. For example ghcr.io/dgarijo/widoco:v1.4.23.

If you want to share data between the Docker Container and your Host, for instance to load a local ontology file (from PATH), you will need to mount the container with host directories. For instance:

docker run -ti --rm \
  -v `pwd`/test:/usr/local/widoco/in:Z \
  -v `pwd`/target/generated-doc:/usr/local/widoco/out:Z \
  dgarijo/widoco -ontFile in/bne.ttl -outFolder out -rewriteAll

Execution options

-analytics CODE: Add a code snippet for Google analytics to track your HTML documentation. You need to add your CODE next to the flag. For example: UA-1234

-confFile PATH: Load your own configuration file for the ontology metadata. Use this option if you want to load your own HTML sections as well. Incompatible with -getOntologyMetadata. See the configuration documentation for more information about the accepted fields.

-crossRef: ONLY generate the overview and cross reference sections. The index document will NOT be generated. The htaccess, provenance page, etc., will not be generated unless requested by other flags. This flag is intended to be used only after a first version of the documentation exists.

-displayDirectImportsOnly: Only those imported ontologies that are directly imported in the ontology being documented.

-doNotDisplaySerializations: The serializations of the ontology will not be displayed.

-excludeIntroduction: Ski