From 45d278d09b7f86adf6a68ddb6e6141a6149eed69 Mon Sep 17 00:00:00 2001 From: Jesper Friis Date: Wed, 6 Nov 2024 14:12:43 +0100 Subject: [PATCH] Added figures to generated documentation (#767) Added figures to generated documentation. If the value of a property matches a regex for a figure on the web, it will be included in the documentation. **Further work**: The figure size should probably be adjusted to not make the table too large. Probably preferred to only show a thumbnail-sized version of the figure in the table. The full size could be shown by clicking. Easier to play with in a following-up PR when this is applied to EMMO. --- Also, added prefLabel as anchoring points such that one can use the browser to easily get documentation of a concept one knows the prefLabel of. For example, entering https://w3id.org/emmo#Atom should bring you to the section in the html doc that documents Atom. --------- Co-authored-by: Francesca L. Bleken <48128015+francescalb@users.noreply.github.com> --- ontopy/ontodoc_rst.py | 59 +++++++++++++++++++++++++++++++-------- ontopy/utils.py | 8 +++--- tests/testonto/mammal.ttl | 11 +++++--- 3 files changed, 59 insertions(+), 19 deletions(-) diff --git a/ontopy/ontodoc_rst.py b/ontopy/ontodoc_rst.py index 20ac86a5f..1c07c76ca 100644 --- a/ontopy/ontodoc_rst.py +++ b/ontopy/ontodoc_rst.py @@ -3,6 +3,7 @@ """ # pylint: disable=fixme,too-many-lines,no-member,too-many-instance-attributes +# pylint: disable=invalid-name import html import re import time @@ -60,6 +61,10 @@ def __init__( self.individuals = set() self.datatypes = set() + # All navigation IDs added by the ontology. Used to warn about + # dublicated IDs + self.navids = set() + if ontology: self.add_ontology(ontology) @@ -137,7 +142,7 @@ def get_refdoc( subsections: str = "all", header: bool = True, ) -> str: - # pylint: disable=too-many-branches,too-many-locals + # pylint: disable=too-many-branches,too-many-locals,too-many-statements """Return reference documentation of all module entities. Arguments: @@ -186,15 +191,31 @@ def add_header(name): ] ) - def add_keyvalue(key, value, escape=True, htmllink=True): - """Help function for adding a key-value row to table.""" - if escape: - value = html.escape(str(value)) - if htmllink: - value = re.sub( - r"(https?://[^\s]+)", r'\1', value - ) - value = value.replace("\n", "
") + def add_keyvalue( + key, value, escape=True, htmllink=True, show_figure=True + ): + """Help function for adding a key-value row to table. + + Arguments: + key: Key to show in the table. + value: Value to show in the table. + htmllink: Whether to add html link to value. + show_figure: Whether to show figure in value column. + + """ + if show_figure and re.match( + r"^https?://[a-zA-Z0-9.+?@/_-]+\.(png|jpg|jpeg|svg|gif)$", + asstring(value, ontology=self.ontology), + ): + value = f'' + else: + if escape: + value = html.escape(str(value)) + if htmllink: + value = re.sub( + r"(https?://[^\s]+)", r'\1', value + ) + value = value.replace("\n", "
") lines.extend( [ " ", @@ -222,11 +243,27 @@ def add_keyvalue(key, value, escape=True, htmllink=True): ) for entity in sorted(maps[subsection], key=get_label): label = get_label(entity) + navid = navid2 = "" + if entity.name in self.navids: + warnings.warn(f"duplicated entity names: {entity.name}") + else: + self.navids.add(entity.name) + navid = f'
' + if hasattr(entity, "prefLabel"): + preflabel = str(entity.prefLabel.first()) + if preflabel != entity.name: + if preflabel in self.navids: + warnings.warn(f"duplicated prefLabel: {preflabel}") + else: + self.navids.add(preflabel) + navid2 = f'
' + lines.extend( [ ".. raw:: html", "", - f'
', + navid, + navid2, "", f"{label}", "^" * len(label), diff --git a/ontopy/utils.py b/ontopy/utils.py index 44f92d1f0..ddb21cce8 100644 --- a/ontopy/utils.py +++ b/ontopy/utils.py @@ -1,7 +1,7 @@ """Some generic utility functions. """ -# pylint: disable=protected-access +# pylint: disable=protected-access,invalid-name import os import sys import re @@ -167,8 +167,7 @@ def asstring( """Returns a string representation of `expr`. Arguments: - expr: The entity, restriction or a logical expression or these - to represent. + expr: The entity, restriction or logical expression to represent. link: A template for links. May contain the following variables: - {iri}: The full IRI of the concept. - {name}: Name-part of IRI. @@ -893,7 +892,8 @@ def copy_annotation(onto, src, dst): elif src in onto: src = onto[src] else: - warnings.warn(f"no such annotation: '{src}' Skip copy annotation...") + + warnings.warn(f"skipping copy for missing source annotation: {src}") return if onto.world[dst]: diff --git a/tests/testonto/mammal.ttl b/tests/testonto/mammal.ttl index 5bc5937d3..c79f5be93 100644 --- a/tests/testonto/mammal.ttl +++ b/tests/testonto/mammal.ttl @@ -5,13 +5,15 @@ @prefix xsd: . @prefix rdfs: . @prefix skos: . +@prefix foaf: . @prefix animal: . @base . rdf:type owl:Ontology ; - owl:versionIRI ; - owl:imports ; - owl:versionInfo "0.1" . + owl:versionIRI ; + owl:imports ; + owl:versionInfo "0.1" ; + foaf:logo "https://upload.wikimedia.org/wikipedia/commons/thumb/8/81/Mammal_collage.png/450px-Mammal_collage.png" . ################################################################# # Classes @@ -20,7 +22,8 @@ ### https://w3id.org/emmo/mammal#Cat :Cat rdf:type owl:Class ; rdfs:subClassOf :Felines ; - skos:prefLabel "Cat"@en . + skos:prefLabel "Cat"@en ; + foaf:img "https://upload.wikimedia.org/wikipedia/commons/thumb/6/68/Orange_tabby_cat_sitting_on_fallen_leaves-Hisashi-01A.jpg/168px-Orange_tabby_cat_sitting_on_fallen_leaves-Hisashi-01A.jpg" . ### https://w3id.org/emmo/mammal#Felines