Merge branch 'ebassi/related-libraries' into 'main'

config: Add "related" configuration key

See merge request GNOME/gi-docgen!145

docs/project-configuration.rst

@@ -51,10 +51,20 @@ The following keys are used, if found:
 ``description`` = ``s``
   A short description of the library.
 
-``dependencies`` = ``dict(s, dict(s, s)``
+``dependencies`` = ``dict(s, dict(s, s))``
   A dictionary of dependencies; each entry in the dictionary has a key in the
   form of ``{namespace}-{version}``, and values in the form of a dictionary
-  with the following keys: ``name``, ``description``, and ``docs_url``.
+  with the following keys: ``name``, ``description``, and ``docs_url``. Each
+  entry in the this dictionary can only describe a namespace included in the
+  introspection data; any other namespace listed here will be ignored. See
+  the ``related`` configuration below.
+
+``related`` = ``dict(s, dict(s, s))``
+  A dictionary of related namespaces; each entry in the dictionary has a key
+  in the form of ``{namespace}-{version}``, and values in the form of a
+  dictionary with the following keys: ``name``, ``description``, and
+  ``docs_url``. Each entry in this dictionary can describe a namespace that
+  is related to the project.
 
 ``devhelp`` = ``b``
   Whether gi-docgen should generate a DevHelp file for the namespace.

gidocgen/config.py

@@ -107,6 +107,24 @@ class GIDocConfig:
 
         return retval
 
+    @property
+    def related(self):
+        library = self._config.get('library', None)
+        if library is None:
+            return {}
+
+        retval = {}
+        dependencies = self._config.get('related', {})
+        for gir_name, dep in dependencies.items():
+            res = {}
+            res['name'] = dep.get('name', 'Unknown')
+            res['description'] = dep.get('description', 'No description provided')
+            res['docs_url'] = dep.get('docs_url', '#')
+            retval[gir_name] = res
+            log.debug(f"Found related library {gir_name}: {res}")
+
+        return retval
+
     @property
     def devhelp(self):
         return self.library.get('devhelp', False)

gidocgen/templates/basic/namespace.html

@@ -83,7 +83,7 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
     </div>
   </header>
 
-  {% if CONFIG.dependencies|length > 0 %}
+  {% if repository.includes %}
   <section>
     <div class="toggle-wrapper">
       <h4 id="dependencies" style="display:flex;">
@@ -93,14 +93,42 @@ SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
 
       <div class="docblock">
         <table>
-        {% for gir_name, dep in CONFIG.dependencies.items() %}
+        {% for ns_name, repo in repository.includes.items() %}
+          {% for _, lib in CONFIG.dependencies.items() if lib.name == repo.namespace.name %}
           <tr>
-            <td><strong>{{ dep.name }}</strong></td>
-            <td>{{ dep.description }}</td>
+            <td><strong>{{ repo.namespace.name }}</strong>&mdash;{{ repo.namespace.version }}</td>
+            <td>{{ lib.description }}</td>
           </tr>
           <tr>
             <td></td>
-            <td><a href="{{ dep.docs_url }}" class="external">Browse documentation</a></td>
+            <td><a href="{{ lib.docs_url }}" class="external">Browse documentation</a></td>
+          </tr>
+          {% endfor %}
+        {% endfor %}
+        </table>
+      </div>
+    </div>
+  </section>
+  {% endif %}
+
+  {% if CONFIG.related|length > 0 %}
+  <section>
+    <div class="toggle-wrapper">
+      <h4 id="related" style="display:flex;">
+        Related libraries
+        <a href="#related" class="anchor"></a>
+      </h4>
+
+      <div class="docblock">
+        <table>
+        {% for gir_name, lib in CONFIG.related.items() %}
+          <tr>
+            <td><strong>{{ lib.name }}</strong></td>
+            <td>{{ lib.description }}</td>
+          </tr>
+          <tr>
+            <td></td>
+            <td><a href="{{ lib.docs_url }}" class="external">Browse documentation</a></td>
           </tr>
         {% endfor %}
         </table>