doc(@supermodule;ldoc.ltp): Draw hierarchy tree

This commit adds a new ldoc custom tag `@supermodule`. It has to be
used at the module level. It should refer to the module
supermodules.

This tag can be used multiple time by the same module, but we ignore
other calls (for now?) as (AFAIK) we only use one way inheritance.

This tag is used in the ldoc template to find modules hierarchy and
draw the inheritance tree. It makes it easy to find and navigate to
parents modules.

docs/config.ld

@@ -456,6 +456,16 @@ add_custom_tag {
     },
 }
 
+-- Define the supermodule class.
+-- This tag should be used at the module level. All properties from the
+-- supermodule will be recursively added to the module by our ldoc template.
+-- @supermodule supermodule
+add_custom_tag {
+    name = "supermodule",
+    hiden = true,
+    auto_subtags = false
+}
+
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 

docs/ldoc.css

@@ -503,3 +503,18 @@ pre .url { color: #272fc2; text-decoration: underline; }
 .index_guides div a:hover {
     background-color: #99b3ec;
 }
+
+/* Inheritance diagram */
+.inheritance .inheritance__level {
+    list-style: none;
+}
+
+.inheritance .inheritance__level__node::before {
+    content: "↳";
+}
+
+.inheritance .inheritance__level__node--root::before {
+    /* simulate the spacing of the arrow character */
+    content: "   ";
+    white-space: pre;
+}

docs/ldoc.ltp

@@ -43,6 +43,29 @@
 # local html_space = function(s) return s:gsub(" ", "%%20") end
 # local no_underscores = function(s) return s:gsub("_", " ") end
 
+# --------- modules hierarchy -------------
+# local hierarchy = {}
+# local curr = module
+# while curr do
+#     hierarchy[#hierarchy + 1] = curr
+#     -- no need to do anything more if there is no explicite @supermodule
+#     if not curr.tags.supermodule then break end
+#     local super = curr.tags.supermodule[1] -- only consider one way inheritance
+#     local found = false
+#     for kind, mods, type in ldoc.kinds() do
+#         for mod in mods() do
+#             local name = display_name(mod)
+#             if name == super then
+#                 curr = mod
+#                 found = true
+#             end
+#             if found then break end
+#         end
+#         if found then break end
+#     end
+#     if not found then curr = nil end
+# end
+
 <!-- Menu -->
 
 <div id="navigation">
@@ -109,6 +132,36 @@
 <h1>Module: <code>$(module.name)</code></h1>
 <p>$(M(module.summary,module))</p>
 <p>$(M(module.description,module))</p>
+
+# if module.tags.supermodule or module.tags.knownusage then
+    <h3>Class Hierarchy</h3>
+    <div class="inheritance">
+# local function draw_hierary_recursifly(i)
+    <ul class="inheritance__level">
+#   if i == #hierarchy then
+        <li class="inheritance__level__node inheritance__level__node inheritance__level__node--root">
+#   else
+        <li class="inheritance__level__node inheritance__level__node">
+#   end
+#   local mod = hierarchy[i]
+#   local name = display_name(hierarchy[i])
+#   if mod == module then
+            <strong>$(name)</strong>
+#   else
+            <a href="$(ldoc.ref_to_module(mod))">$(name)</a>
+#   end
+        </li>
+#   if i > 1 then
+        <li>
+#           draw_hierary_recursifly(i - 1)
+        </li>
+#   end
+    </ul>
+# end
+# draw_hierary_recursifly(#hierarchy)
+    </div>
+# end
+
 #   if module.tags.include then
         $(M(ldoc.include_file(module.tags.include)))
 #   end