Merge pull request #15 from potassco/14-add-a-glossary-for-predicates

14 add a glossary for predicates

src/mkdocstrings_handlers/asp/features/glossary.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mkdocstrings_handlers.asp.document import Document
+from mkdocstrings_handlers.asp.semantics.predicate_documentation import PredicateDocumentation
+
+
+@dataclass
+class GlossaryEntry:
+    """
+    A class to represent a glossary entry.
+    """
+
+    signature: str
+    """ The signature of the predicate. """
+    description: str
+    """ The description of the predicate. """
+    parameters: dict[str, str]
+    """ The parameters and their descriptions of the predicate. """
+
+
+@dataclass
+class Glossary:
+    """
+    A class to represent a glossary.
+    """
+
+    entries: list[GlossaryEntry]
+    """ The entries of the glossary. """
+
+    @staticmethod
+    def from_document(document: Document) -> Glossary:
+        """
+        Initialize the glossary from an ASP document.
+
+        Args:
+            document: The ASP document.
+
+        Returns:
+            The glossary.
+        """
+
+        entries: list[GlossaryEntry] = []
+
+        for predicate_documentation in document.predicate_documentations:
+            entry = GlossaryEntry(
+                signature=predicate_documentation.literal.text,
+                description=predicate_documentation.description,
+                parameters=predicate_documentation.parameter_descriptions,
+            )
+            entries.append(entry)
+
+        entries.sort(key=lambda x: x.signature)
+
+        return Glossary(entries)

src/mkdocstrings_handlers/asp/handler.py

@@ -7,8 +7,9 @@
 
 from mkdocstrings.handlers.base import BaseHandler
 
-from mkdocstrings_handlers.asp.dependency_graph import get_dependency_graph
 from mkdocstrings_handlers.asp.document import Document
+from mkdocstrings_handlers.asp.features.dependency_graph import get_dependency_graph
+from mkdocstrings_handlers.asp.features.glossary import Glossary
 
 
 class ASPHandler(BaseHandler):
@@ -73,6 +74,7 @@ def collect(self, identifier: str, config: dict) -> dict | None:
             "title": document.title,
             "encoding": document.content,
             "dependency_graph": get_dependency_graph(document),
+            "glossary": Glossary.from_document(document),
         }
 
         return data

src/mkdocstrings_handlers/asp/semantics/predicate_documentation.py

@@ -6,7 +6,6 @@
 
 from mkdocstrings_handlers.asp.semantics.block_comment import BlockComment
 from mkdocstrings_handlers.asp.semantics.literal import Literal
-from mkdocstrings_handlers.asp.tree_sitter.debug import print_tree
 from mkdocstrings_handlers.asp.tree_sitter.node_kind import NodeKind
 from mkdocstrings_handlers.asp.tree_sitter.parser import ASPParser
 from mkdocstrings_handlers.asp.tree_sitter.traverse import traverse

src/mkdocstrings_handlers/asp/templates/material/dependency_graph.html.jinja

@@ -1,15 +1,15 @@
 {% set mermaid_diagram %}
 ```mermaid
 flowchart LR
-    {% for dependency in dependency_graph %}
+    {%- for dependency in dependency_graph %}
     {{dependency}}(["{{dependency}}"])
-         {% for positive in dependency_graph[dependency].positive %}
+         {%- for positive in dependency_graph[dependency].positive %}
          {{dependency}} --> {{positive}}
-         {% endfor %}
-         {% for negative in dependency_graph[dependency].negative %}
+         {%- endfor %}
+         {%- for negative in dependency_graph[dependency].negative %}
          {{dependency}} -.-> {{negative}}
-         {% endfor %}
-    {% endfor %}
+         {%- endfor %}
+    {%- endfor %}
     classDef all fill:#00000000
     classDef in stroke:#9178C6,stroke-width:3px;
     classDef out stroke:#52BF54,stroke-width:3px;

src/mkdocstrings_handlers/asp/templates/material/documentation.html.jinja

@@ -9,3 +9,9 @@
 {% if dependency_graph %}
     {% include 'dependency_graph.html.jinja' %}
 {% endif %}
+
+{% if glossary %}
+    {% include 'separator.html.jinja' %}
+
+    {% include 'glossary.html.jinja' %}
+{% endif %}

src/mkdocstrings_handlers/asp/templates/material/glossary.html.jinja

@@ -0,0 +1,21 @@
+{% set glossary_block %}
+## :material-format-list-bulleted-square: Glossary
+
+{% for entry in glossary.entries %}
+#### <code class="doc-symbol doc-symbol-heading doc-clingo-symbol-predicate"></code> {{ entry.signature }}
+
+{{ entry.description }}
+
+{%- if entry.parameters %}
+
+| Parameter | Description                        |
+| :-------- | :--------------------------------- |
+{%- for param, description in entry.parameters.items() %}
+| `{{ param }}` | {{ description }} |
+{%- endfor %}
+{% endif %}
+{% endfor %}
+{% endset %}
+
+
+{{ glossary_block | convert_markdown(1, "glossary") }}

src/mkdocstrings_handlers/asp/templates/material/separator.html.jinja

@@ -0,0 +1,4 @@
+{% set separator %}
+---------
+{% endset %}
+{{ separator | convert_markdown(1, "separator") }}