gendocs run on multiple ontologies produces randomly-sorted index.html

[ajnelson-nist]

I am involved in a community that is considering use gendocs to generate ontology documentation. Our ontology file organization uses one "root" (or "umbrella") ontology that imports "sub"-ontologies stored nearby in a directory structure:

example_ontology/bar/bar.ttl
example_ontology/central/central.ttl
example_ontology/foo/foo.ttl

(central.ttl's name is listed here as a contrived example for sorting illustration later. Might be better as e.g. main.ttl or root.ttl.)

central.ttl has the <http://example.org/example_ontology> a owl:Ontology . definition, several owl:imports statements for the bar and foo ontologies that are defined in their respective .ttl files, and then leaves any concept definitions to bar, foo, etc.

If we run ontospy gendocs --type 2 on the example_ontology directory, the index.html file that is generated lists all of the ontology definitions on one page, which is desired behavior. But, it lists them in a random order, which makes for either a confusing read, or for manual output editing that doesn't feel like it should be necessary.

I looked through the code base for where a call to sorted() could be added, but unfortunately I could not figure out where the order is determined when building index.html.

It would be nice if the sort order were at least alphabetical by the ontology IRIs. It would be better if some of the import topology were considered, i.e. putting the ontologies not imported by any others first. (So, in the above example, the ontologies would be sorted central, bar, foo.)

I think it would be most desirable to at least have the output, especially index.html, not change between two runs on the same input files & day.

[lambdamusic]

Hi @ajnelson-nist - thanks for the detailed feedback, and sorry for the slow reply.

I've just pushed a release that enforces an alphabetical order based on ontologies URIs.

That should solve your problem, at least partially.

In future versions I'll be looking at deriving the order from the owl:imports statements. Or maybe even better, let users define a custom ordering.

PS you can pass a --title parameter to create a more sensible title for the documentation, eg
ontospy gendocs rdf/folder --type 2 --title "My fantastic multi-ontology knowledge graph"

[ajnelson-nist]

Thank you very much!