OntologyDocumentation

OntologyDocumentation

The OntologyDocumentation is a little side project that was created by Rene Ranzinger to auto-generate a Word documentation file out of the information in the ontology. This generator was used for most of the ontology versions to generate the documentation. But the program code is general enough to be used for other ontologies, too.

Configuration file

The configuration file controls the output in the Word file. It consists of three major sections. Namespaces If in the Word file prefixes should be used instead of complete URIs, these prefixes need to be specified in the first section. For any base URI a prefix is defined the URI part gets replaced by prefix: during the Word file generation.

<namespaces>
        <namespace prefix="glycan" uri="http://purl.jp/bio/12/glyco/glycan#" />
</namespaces>

Text There are only two static text fragments that are integrated into the word file. The document_title will be used as title of the Word document. The namespace text will be added before the namespaces table in the word file.

<texts>
        <text id="document_title">GlycoRDF version 0.17</text>
        <text id="namespace">The following RDF namespaces and prefixes will be used in the documentation.</text>
</texts>

Classes A list of classes that should be added to the documentation. Any class not listed in the section will be ignored. For each class a numerical order in the document, the URI of the class (do not use prefix here) and a boolean flag indicating if the instances of the class should be added to the Word file has to be specified. If class to be become sub-chapter of another class (to reflect inheritance hierarchy) the correspond tag has to be a sub-tag of the parent classes tag.

<classes>
        <class order="1" name="http://purl.jp/bio/12/glyco/glycan#carbohydrate_format" instances="true"/>
        <class order="4" name="http://purl.jp/bio/12/glyco/glycan#compound" instances="true">
            <class order="1" name="http://purl.jp/bio/12/glyco/glycan#aglycon" instances="true"/>
        </class>
</classes>

The Java class edu.uga.ccrc.ontology.doc.ClassHierarchyExtractor can be used to create the classes section for the complete list of all classes in an ontology. Afterwards the ordering can be adjusted, classes can be excluded or the chapter structure can be changed.

complementary.xlsx

This Excel file contains information about predicates that are not defined in the ontology itself but are reused from another ontology. If these predicates should be added to the documentation they need to be listed in this file.

• Column A: URI of the domain of the predicate (do not use prefix)
• Column B: URI of the predicate (do not use prefix)
• Column C: URI of the range of the predicate (do not use prefix)
• Column D: Descritption
• Column E: Functional (yes otherwise empty)

Start the program

• Checkout the OntologyDocumentation source code from the repository.
• Edit edu.uga.ccrc.ontology.doc.OntologyDocumentation
• Line 14: Change xmlFile to the configuration file of your project
• Line 15: In new OntologyHandler replace the ontology name with your ontology (first parameter), base URI of your ontology (second parameter)
• Line 16: Change the name of the output file to the name you would like to use ("ontology/documentation.docx")
• Run the java class

Word output format

The Word documentation file starts with the headline from the configuration file followed by the list of namespaces defined in the configuration file in form of a table (Prefix used in the documentation and URI). For each specified in the configuration the following information is provided:

• Name of the class as headline (label from the ontology otherwise URI)
• Description of the class in the ontology as text below the headline
• URI of the class
• Superclass
• Instances of the class (if instances in the configuration file is set to true)
• URI of the instance
• Label of the instance
• Description of the instance
• List of predicates that have this class as domain
• Predicate URI
• Range
• Functional (yes or empty)
• Description of the predicate