From f96665b79a96c3e25d9b28d0d0009973d4698683 Mon Sep 17 00:00:00 2001
From: Jesper Friis <jesper.friis@sintef.no>
Date: Sun, 2 Jun 2024 15:02:17 +0200
Subject: [PATCH] Added figures to generated documentation

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.
---
 ontopy/ontodoc_rst.py | 48 ++++++++++++++++++++++++++++++++++---------
 ontopy/utils.py       |  5 ++++-
 2 files changed, 42 insertions(+), 11 deletions(-)

diff --git a/ontopy/ontodoc_rst.py b/ontopy/ontodoc_rst.py
index 20ac86a5..0d9d4bd8 100644
--- a/ontopy/ontodoc_rst.py
+++ b/ontopy/ontodoc_rst.py
@@ -60,6 +60,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 +141,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 +190,23 @@ def add_header(name):
                 ]
             )
 
-        def add_keyvalue(key, value, escape=True, htmllink=True):
+        def add_keyvalue(
+            key, value, escape=True, htmllink=True, show_figure=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>")
+            if show_figure and re.match(
+                r"^(http://|https://)[a-zA-Z.+?@/_-]+\.(png|jpg|jpeg|svg|gif)$",
+                value,
+            ):
+                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 +234,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),
diff --git a/ontopy/utils.py b/ontopy/utils.py
index aba32af7..135aa05f 100644
--- a/ontopy/utils.py
+++ b/ontopy/utils.py
@@ -888,8 +888,11 @@ def copy_annotation(onto, src, dst):
     """
     if onto.world[src]:
         src = onto.world[src]
-    else:
+    elif src in onto:
         src = onto[src]
+    else:
+        warnings.warn(f"skipping copy for missing source annotation: {src}")
+        return
 
     if onto.world[dst]:
         dst = onto.world[dst]