Ontodoc example in documentation (#630)

* Updated excel2onto example in documentation

* Updated index in mkdocs for excel2onto-example

* If excel file contains relative paths perform command in same folder as
excelfile

* Improved error message when missing ontology to be updated

* Added test

examples/ontology-from-excel/README.md

@@ -0,0 +1,25 @@
+# Generate an ontology from excel
+
+This directory contains an example xlsx-file for how to document ontology entities (classes, object properties, annotation properties and data properties) in an Excel workbook.
+This workbook can then be used to generate a new ontology or update an already existing ontology with new entities (existing entities are not updated).
+
+Please refer to the (documentation)[https://emmo-repo.github.io/EMMOntoPy/latest/api_reference/ontopy/excelparser/] for full explanation of capabilities.
+
+The file `tool/onto.xlsx` contains examples on how to do things correctly as well as incorrectly.
+The tool will by default exit without generating the ontology if it detects concepts defined incorrectly.
+However, if the argument force is set to True, it will skip concepts that are erroneously defined
+and generate the ontology with what is availble.
+
+To run the tool directly
+```console
+cd tool # Since the excel file provides a relative path to an imported ontology
+excel2onto onto.xlsx # This will fail
+excel2onto --force onto.xlsx
+```
+We suggest developing your excelsheet without fails as once it starts getting big it is difficult to see what is wrong or correct.
+
+It is also possible to generate the ontology in python.
+Look at the script make_onto.py for an example.
+
+That should be it.
+Good luck!

examples/ontology-from-excel/make_microstructure_onto.py → examples/ontology-from-excel/make_onto.py

@@ -9,8 +9,14 @@
 
 thisdir = Path(__file__).resolve().parent
 ontology, catalog, errdict = create_ontology_from_excel(
-    thisdir / "tool/microstructure.xlsx"
+    thisdir / "tool/onto.xlsx",
+    force=True,  # Note will force generation of the ontology.
 )
 
-ontology.save("microstructure_ontology.ttl", format="turtle", overwrite=True)
+
+# Save the ontology and write out the catalog
+ontology.save("onto.ttl", format="turtle", overwrite=True)
 write_catalog(catalog)
+
+# Look at the error dictionary
+print(errdict.keys())

examples/ontology-from-excel/tool/imported_onto/catalog-v001.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+    <group id="Folder Repository, directory=, recursive=true, Auto-Update=false, version=2" prefer="public" xml:base="">
+	    <uri name="http://ontology.info/ontology/0.1.0" uri="./ontology.ttl"/>
+	    <uri name="http://ontology.info/ontology/0.1.0/subontology" uri="./subontology.ttl"/>
+    </group>
+</catalog>

examples/ontology-from-excel/tool/imported_onto/ontology.ttl

@@ -0,0 +1,18 @@
+@prefix : <http://ontology.info/ontology#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix xml: <http://www.w3.org/XML/1998/namespace> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+@base <http://ontology.info/ontology> .
+
+<http://ontology.info/ontology> rdf:type owl:Ontology ;
+                             owl:versionIRI <http://ontology.info/ontology/0.1.0> ;
+                             owl:imports <http://ontology.info/ontology/0.1.0/subontology> ;
+			     owl:versionInfo "0.1.0" .
+
+
+:testclass rdf:type owl:Class ;
+    rdfs:subClassOf owl:Thing ;
+    skos:prefLabel "TestClass"@en .

examples/ontology-from-excel/tool/imported_onto/subontology.ttl

@@ -0,0 +1,21 @@
+@prefix : <http://ontology.info/subontology#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix xml: <http://www.w3.org/XML/1998/namespace> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+@base <http://ontology.info/subontology> .
+
+<http://ontology.info/subontology> rdf:type owl:Ontology ;
+    owl:versionIRI <http://ontology.info/ontology/0.1.0/subontology> .
+
+
+# Annotations
+skos:prefLabel rdf:type owl:AnnotationProperty .
+skos:altLabel rdf:type owl:AnnotationProperty .
+
+
+:testclass2 rdf:type owl:Class ;
+    rdfs:subClassOf owl:Thing ;
+    skos:prefLabel "TestClass2"@en .

mkdocs.yml

@@ -90,6 +90,7 @@ nav:
     - Examples:
       - EMMOdoc: examples/emmodoc/README.md
       - Jupyter visualization: examples/jupyter-visualization/README.md
+      - Ontology generation from Excel: examples/ontology-from-excel/README.md
   - ... | developers/**
   - Changelog: CHANGELOG.md
   - ... | api_reference/**

tests/tools/test_excel2onto.py

@@ -55,3 +55,10 @@ def test_run(get_tool: "Callable[[str], ModuleType]", tmpdir: "Path") -> None:
             str(test_file),
         ]
     )
+
+    # Test Error raised if ontology to be updated does not exist
+    with pytest.raises(
+        FileNotFoundError,
+        match="The output ontology to be updated does not exist",
+    ):
+        excel2onto.main([f"--output=onto_not_created.ttl", str(test_file)])

tools/excel2onto

@@ -80,12 +80,16 @@ def main(argv: list = None):
         except FileNotFoundError as err:
             if args.force:
                 warnings.warn(
-                    "Did not find the input ontology, "
+                    "Did not find the output ontology to be updated, "
                     "will fully generate a new one."
                 )
                 input_ontology = None
             else:
-                raise err
+                raise FileNotFoundError(
+                    "The output ontology to be updated "
+                    "does not exist. Missing file is: ",
+                    args.output,
+                ) from err
 
     try:
         ontology, catalog, _ = create_ontology_from_excel(