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 <[email protected]>

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'<a href="\1">\1</a>', value
-                )
-            value = value.replace("\n", "<br>")
+        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'<img src="{value}">'
+            else:
+                if escape:
+                    value = html.escape(str(value))
+                if htmllink:
+                    value = re.sub(
+                        r"(https?://[^\s]+)", r'<a href="\1">\1</a>', value
+                    )
+                value = value.replace("\n", "<br>")
             lines.extend(
                 [
                     "  <tr>",
@@ -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'   <div id="{entity.name}"></div>'
+                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'   <div id="{preflabel}"></div>'
+
                 lines.extend(
                     [
                         ".. raw:: html",
                         "",
-                        f'   <div id="{entity.name}"></div>',
+                        navid,
+                        navid2,
                         "",
                         f"{label}",
                         "^" * len(label),

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]:

tests/testonto/mammal.ttl

@@ -5,13 +5,15 @@
 @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#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
 @prefix animal: <https://w3id.org/emmo/animal#> .
 @base <https://w3id.org/emmo/domain/mammal#> .
 
 <https://w3id.org/emmo/domain/mammal> rdf:type owl:Ontology ;
-                                owl:versionIRI <https://w3id.org/emmo/domain/mammal/0.1> ;
-                                owl:imports <https://w3id.org/emmo/domain/animal/0.1> ;
-                                owl:versionInfo "0.1" .
+    owl:versionIRI <https://w3id.org/emmo/domain/mammal/0.1> ;
+    owl:imports <https://w3id.org/emmo/domain/animal/0.1> ;
+    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