clindocs 1.5.2__py3-none-any.whl

clindocs-1.5.2.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: clindocs
+Version: 1.5.2
+Summary: Mkdocs plugin to generate documentation from clingo files
+Author-email: Potassco <hahnmartinlu@uni-potsdam.de>
+License: MIT License
+        
+        Copyright (c) 2024 Potassco
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/potassco/clindocs.git/
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clingo
+Requires-Dist: mkdocstrings>=1.0.0
+Requires-Dist: tree-sitter
+Requires-Dist: tree-sitter-clingo>=1.0.5
+Requires-Dist: pydantic
+Requires-Dist: pygments_clingo
+Requires-Dist: mkdocs>=1.5
+Requires-Dist: mkdocs-material>=9.5
+Requires-Dist: mkdocs-autorefs>=1.4
+Provides-Extra: format
+Requires-Dist: black; extra == "format"
+Requires-Dist: isort; extra == "format"
+Requires-Dist: autoflake; extra == "format"
+Provides-Extra: lint-pylint
+Requires-Dist: pylint; extra == "lint-pylint"
+Requires-Dist: djlint; extra == "lint-pylint"
+Provides-Extra: typecheck
+Requires-Dist: types-setuptools; extra == "typecheck"
+Requires-Dist: mypy; extra == "typecheck"
+Requires-Dist: types-Markdown; extra == "typecheck"
+Requires-Dist: types-Pygments; extra == "typecheck"
+Provides-Extra: test
+Requires-Dist: coverage[toml]; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: doc
+Requires-Dist: mkdocstrings[python]; extra == "doc"
+Requires-Dist: mkdocs-literate-nav; extra == "doc"
+Provides-Extra: dev
+Requires-Dist: clindocs[doc,lint_pylint,test,typecheck]; extra == "dev"
+Dynamic: license-file
+
+# clindocs
+
+**clindocs** is an automated documentation tool tailored for **Answer Set
+Programming (ASP)** code. Built on [MkDocs](https://www.mkdocs.org/) and
+[mkdocs-material](https://squidfunk.github.io/mkdocs-material/), it streamlines
+the creation of high-quality documentation with the following features:
+
+- **Render encodings**: Automatically format ASP encodings with comments
+  written in Markdown.
+- **Predicate analysis**: Collect and document predicates used across included
+  files.
+- **Navigation-friendly documentation**: Generate organized predicate
+  documentation with intuitive navigation.
+- **Input/output identification**: Detect and highlight input and output
+  predicates.
+- **Dependency graphs**: Visualize dependencies between predicates and files.
+
+For installation instructions and detailed usage, visit our
+[official documentation](https://potassco.org/clindocs/docs).

clindocs-1.5.2.dist-info/RECORD

@@ -0,0 +1,41 @@
+clindocs-1.5.2.dist-info/licenses/LICENSE,sha256=ENv21OEPTlPYM34OARsrJK5nyORaoT0-Bp-H3Xa3gyg,1065
+mkdocstrings_handlers/asp/__init__.py,sha256=3R9Ma3P3-t8LJtHm1RCoEmOhpnORGVOSx4FXPx2ZPs8,150
+mkdocstrings_handlers/asp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/asp/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/asp/_internal/config.py,sha256=WdU-m_3PR5Et8ESJr2hWRa4de6_WoptGOGemRs7mreI,4211
+mkdocstrings_handlers/asp/_internal/domain.py,sha256=pjtl7djVbs7ID4GVzVFcHLAPLzkpPbbJLUKYrWOfw3Y,3923
+mkdocstrings_handlers/asp/_internal/error.py,sha256=1KeOtM31AKvCELVi4kcqnXQjIhy1hP_7XfeSaUbH4Wc,169
+mkdocstrings_handlers/asp/_internal/handler.py,sha256=TYMPVJtQ5gGVobFDxsIhfJLul8UWEnta1PcEy-bep7A,5299
+mkdocstrings_handlers/asp/_internal/collect/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/asp/_internal/collect/debug.py,sha256=zUPYCq-h-iW7_tCuDv-zdBzvAYqdW6FjnqIbMg3WJyw,595
+mkdocstrings_handlers/asp/_internal/collect/extractors.py,sha256=2klxVlYnV-fhKWt2Zg2Wg7EljWdNGWbKDE_Pit6Ogp8,9052
+mkdocstrings_handlers/asp/_internal/collect/load.py,sha256=LQakM5oVIcELcy3-w6tQSJTAxeh36p12ZnxD9mo5bZY,3270
+mkdocstrings_handlers/asp/_internal/collect/syntax.py,sha256=8oH7BOc_Yd342QD_SindIWyJu0HGUI79OqNmk38VHGc,2747
+mkdocstrings_handlers/asp/_internal/collect/queries/body.scm,sha256=yfkZakz32nkbmSZJD6udhe2FrtaVrZ27H778dbhcod4,305
+mkdocstrings_handlers/asp/_internal/collect/queries/documentation_argument.scm,sha256=WdgpiFuSRWdTqVJChC_sgZEM8o_zBox3p71ojkCqsQs,67
+mkdocstrings_handlers/asp/_internal/collect/queries/documentation_predicate.scm,sha256=VbkRK8PxkeXArtu8LngZU9M-mhmibzNgJ5TkL2tfsGM,223
+mkdocstrings_handlers/asp/_internal/collect/queries/head.scm,sha256=_fX566sB8zS1QZqQijD1SZlRQpjZwhxXiOLFT4NiNtg,1105
+mkdocstrings_handlers/asp/_internal/collect/queries/predicate.scm,sha256=Ga9Tm7zM4ti-W3mbD9raYP6jF7eFYjmGYibZKo5Cww0,692
+mkdocstrings_handlers/asp/_internal/collect/queries/show.scm,sha256=lhQ8pez9EKIl8cvXDvLGO7FGQSdESQkfyBZ2YstmQ60,199
+mkdocstrings_handlers/asp/_internal/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocstrings_handlers/asp/_internal/render/dependency_graph_context.py,sha256=QnJ50hpkfRP--T-zVHN2jI7RGJmJ7_DXmuY5G6UUMJ0,2232
+mkdocstrings_handlers/asp/_internal/render/encodings_context.py,sha256=ystrk5ravvGrXNI2hSFHagilEuiuVgLAsANLtvtDQOo,4358
+mkdocstrings_handlers/asp/_internal/render/glossary_context.py,sha256=UxqDaKG-SUK2jSWKeHlZq5RxGUizNKY4cWODz0yJ-vE,4853
+mkdocstrings_handlers/asp/_internal/render/predicate_info.py,sha256=dvXGS4lnexUXkVVGIvWhhCkyYlPtHS6h27hPVFUcbSk,7110
+mkdocstrings_handlers/asp/_internal/render/predicate_table_context.py,sha256=I6wl1YejWEce1tEV7cgtLq_TYP8b2v7nTYpjL0LSFsk,1793
+mkdocstrings_handlers/asp/_internal/render/render_context.py,sha256=uhoe1tHCpyRd3oB6_SDkV8qHyw71eeaLpIinB_kNUR8,2654
+mkdocstrings_handlers/asp/templates/material/dependency_graph.html.jinja,sha256=PXLhW2zlYMFsQSzZF476d0wEV15kjYTJgUCo4bIr_6g,2913
+mkdocstrings_handlers/asp/templates/material/documentation.html.jinja,sha256=B4tepM5f0HjzUQxPLK-HwCKSV1Qye5Lwy0qXkZvQofQ,439
+mkdocstrings_handlers/asp/templates/material/encodings.html.jinja,sha256=rfZQXgMyqcy_rLMDr2zE2Tjb25QRVuF1KDnQRXMo4j0,3838
+mkdocstrings_handlers/asp/templates/material/glossary.html.jinja,sha256=OHXeoXMpgnXrLhRI0JUw5pWTxBE04b9xYBDv8b_rOOM,2649
+mkdocstrings_handlers/asp/templates/material/glossary_references.html.jinja,sha256=3YTnNMAQGm66YK89F8oefEMHDppmxnXql0yp8m5I4ZQ,1918
+mkdocstrings_handlers/asp/templates/material/icons.html.jinja,sha256=nCi2uDpWEnCXbTa6csULENr73bkLVQokXCT_m0XF6Fg,1993
+mkdocstrings_handlers/asp/templates/material/predicate_table.html.jinja,sha256=BxxhTEUs7QE8J2HlHIbs-eXv9L10_srAyQER0O1kmHg,1562
+mkdocstrings_handlers/asp/templates/material/separator.html.jinja,sha256=oX1ZUWDBCFcR2uGLrcR_fZYwSFD6qiwIeigq0KZ7PEA,61
+mkdocstrings_handlers/asp/templates/material/source.html.jinja,sha256=cs7vXtFhJ2_WrxljVKLE408MtV5bFUkFC2h2zVMErS0,159
+mkdocstrings_handlers/asp/templates/material/style.css,sha256=TD6mkJY7jxxyEdjA3-FZaTwXYFdgqhiavui7vltIa_M,2778
+clindocs-1.5.2.dist-info/METADATA,sha256=x94Fs6M3QFbBoK9G29rMK2_4NfYtVL9hpvECXHnr5-Q,3580
+clindocs-1.5.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+clindocs-1.5.2.dist-info/entry_points.txt,sha256=r4jCxLx7C7iZyzmXNS5d_XnMEeRjUPXwqgRfgVnRtqA,88
+clindocs-1.5.2.dist-info/top_level.txt,sha256=IP9FE6TMun3TXULzTNhW_Y0Tlj9Dh3J4k1QHrzs9NnY,22
+clindocs-1.5.2.dist-info/RECORD,,

clindocs-1.5.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clindocs-1.5.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocstrings.handlers]
+clingo = mkdocstrings_handlers.asp._internal.handler:ASPHandler

clindocs-1.5.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Potassco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clindocs-1.5.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+mkdocstrings_handlers

mkdocstrings_handlers/asp/__init__.py

@@ -0,0 +1,5 @@
+"""Entry point of the mkdocstrings handler module."""
+
+from mkdocstrings_handlers.asp._internal.handler import get_handler
+
+__all__ = ["get_handler"]

mkdocstrings_handlers/asp/_internal/collect/debug.py

@@ -0,0 +1,19 @@
+"""Utility functions for debugging tree-sitter trees."""
+
+from tree_sitter import Node
+
+
+def print_tree(node: Node, source: bytes, depth: int) -> None:
+    """Recursively print the tree structure of a node.
+    Args:
+        node: The node to print.
+        source: The source code from which the node was created.
+        depth: The current depth in the tree.
+    """
+
+    node_text = node.text.decode("utf-8") if node.text is not None else ""
+
+    print(f"{'  ' * depth}{node.grammar_name} {node.id}: {node_text}")
+
+    for child in node.children:
+        print_tree(child, source, depth + 1)

mkdocstrings_handlers/asp/_internal/collect/extractors.py

@@ -0,0 +1,317 @@
+"""Extractors for various ASP constructs from Tree-sitter nodes."""
+
+from collections import defaultdict
+from pathlib import Path
+
+from tree_sitter import Node
+
+from mkdocstrings_handlers.asp._internal.collect.syntax import Queries
+from mkdocstrings_handlers.asp._internal.domain import (
+    ArgumentDocumentation,
+    BlockComment,
+    Include,
+    LineComment,
+    Predicate,
+    PredicateDocumentation,
+    Show,
+    ShowStatus,
+    Statement,
+)
+from mkdocstrings_handlers.asp._internal.error import ExtractionError
+
+
+def get_node_text(node: Node | None) -> str:
+    """
+    Safely extracts and decodes text from a Tree-sitter node.
+
+    Args:
+        node: The Tree-sitter node.
+
+    Returns:
+        The decoded text content of the node.
+
+    Raises:
+        ExtractionError: If the node is None or has no text.
+    """
+    if node is None:
+        raise ExtractionError("Expected a node, but got None.")
+
+    if node.text is None:
+        # This usually happens with 'missing' nodes in Tree-sitter (syntax errors)
+        raise ExtractionError(f"Node {node.type} exists but has no text content.")
+
+    return node.text.decode("utf-8")
+
+
+def get_capture_text(captures: dict[str, list[Node]], key: str, index: int = 0) -> str:
+    """
+    Safely retrieves the text from a capture group.
+
+    Args:
+        captures: The dictionary of captured nodes.
+        key: The capture group name (e.g., "identifier").
+        index: Which item in the capture list to retrieve (default 0).
+
+    Returns:
+        The decoded text content of the specified capture.
+
+    Raises:
+        ExtractionError: If the capture group is missing, empty, or the index is out of
+        bounds.
+    """
+    nodes = captures.get(key)
+
+    if not nodes:
+        raise ExtractionError(f"Required capture group '{key}' is missing or empty.")
+
+    if index >= len(nodes):
+        raise ExtractionError(f"Capture group '{key}' does not have an element at index {index}.")
+
+    return get_node_text(nodes[index])
+
+
+def extract_include(node: Node, parent_file_path: Path) -> Include:
+    """
+    Extract an Include from a node.
+
+    Args:
+        node: The node representing the include.
+        base_path: The base path of the current file.
+
+    Returns:
+        The created Include.
+    """
+    # If the node is an include,
+    # then the first child is the include directive
+    # and the second child is the file path.
+
+    # The second child of the file path is the file path
+    # as a string fragment without the quotes.
+    file_path_node = node.children[1]
+    file_path = Path(get_node_text(file_path_node.children[1]))
+    resolved_path = parent_file_path.parent / file_path
+
+    return Include(row=node.start_point.row, content=get_node_text(node), path=resolved_path)
+
+
+def extract_predicates(node: Node) -> list[Predicate]:
+    """
+    Extract a Predicate from a node.
+
+    Args:
+        node: A `literal` node representing the predicate.
+
+    Returns:
+        The created Predicate.
+    """
+    captures = Queries.PREDICATE.captures(node)
+
+    identifier = get_node_text(captures["identifier"][0])
+    is_negated = len(captures.get("negation", [])) > 0
+
+    if "term_group" not in captures:
+        return [Predicate(identifier=identifier, arity=0, negation=is_negated)]
+
+    predicates = []
+    for group_node in captures["term_group"]:
+        arity = group_node.named_child_count
+
+        predicates.append(Predicate(identifier=identifier, arity=arity, negation=is_negated))
+
+    return predicates
+
+
+def extract_show(node: Node) -> Show:
+    """
+    Extract a Show directive from a node.
+
+    Args:
+        node: A `show_signature` or `show_term` node representing the show directive.
+
+    Returns:
+        The created Show directive.
+    """
+    captures = Queries.SHOW.captures(node)
+
+    raw_identifier = captures.get("identifier", [])
+    raw_arity = captures.get("arity", [])
+    raw_terms = captures.get("term", [])
+
+    identifier: str | None = get_node_text(raw_identifier[0]) if raw_identifier else None
+    arity: int | None = int(get_node_text(raw_arity[0])) if raw_arity else None
+    predicate: Predicate | None = None
+    status = ShowStatus.EXPLICIT
+
+    if raw_terms:
+        status = ShowStatus.PARTIAL
+        arity = len(raw_terms)
+
+    if identifier is not None and arity is not None:
+        predicate = Predicate(
+            identifier=identifier,
+            arity=arity,
+        )
+
+    return Show(
+        row=node.start_point.row,
+        content=get_node_text(node),
+        predicate=predicate,
+        status=status,
+    )
+
+
+def extract_line_comment(node: Node) -> LineComment:
+    """
+    Extract a LineComment from a node.
+
+    Args:
+        node: A `line_comment` node representing the line comment.
+
+    Returns:
+        The created LineComment.
+    """
+    return LineComment(
+        row=node.start_point.row,
+        content=get_node_text(node).removeprefix("%"),
+    )
+
+
+def extract_block_comment(node: Node) -> BlockComment:
+    """
+    Extract a BlockComment from a node.
+
+    Args:
+        node: A `block_comment` node representing the block comment.
+
+    Returns:
+        The created BlockComment.
+    """
+    return BlockComment(
+        row=node.start_point.row,
+        content=get_node_text(node).removeprefix("%*").removesuffix("*%"),
+    )
+
+
+def extract_bare_statement(node: Node) -> Statement:
+    """
+    Extract a Statement without predicate tracking.
+
+    Args:
+        node: A node representing the statement.
+
+    Returns:
+        The created Statement.
+    """
+    return Statement(
+        row=node.start_point.row,
+        content=get_node_text(node),
+        provided_predicates=[],
+        needed_predicates=[],
+    )
+
+
+def extract_statement(node: Node) -> Statement:
+    """
+    Extract a Statement from a node.
+
+    Args:
+        node: A node representing the statement.
+
+    Returns:
+        The created Statement.
+    """
+    head_node = node.child_by_field_name("head")
+    body_node = node.child_by_field_name("body")
+
+    captures = defaultdict(list)
+
+    if head_node:
+        # We don't use the head_node here
+        # because `head` is a supertype in the current grammar
+        # which leads to query difficulties with literals
+        head_captures = Queries.HEAD.captures(node)
+        for key, nodes in head_captures.items():
+            captures[key].extend(nodes)
+
+    if body_node:
+        body_captures = Queries.BODY.captures(body_node)
+        for key, nodes in body_captures.items():
+            captures[key].extend(nodes)
+
+    provided_predicates = [pred for node in captures.get("provided", []) for pred in extract_predicates(node)]
+    needed_predicates = [pred for node in captures.get("needed", []) for pred in extract_predicates(node)]
+
+    return Statement(
+        row=node.start_point.row,
+        content=get_node_text(node),
+        provided_predicates=provided_predicates,
+        needed_predicates=needed_predicates,
+    )
+
+
+def extract_argument_documentation(node: Node) -> ArgumentDocumentation:
+    """
+    Extract an ArgumentDocumentation from a node.
+
+    Args:
+        node: The node representing the argument documentation.
+
+    Returns:
+        The created ArgumentDocumentation.
+    """
+    captures = Queries.DOC_ARGUMENT.captures(node)
+
+    identifier = get_capture_text(captures, "identifier", 0)
+    description = get_node_text(captures["description"][0]).strip() if captures.get("description") else ""
+
+    return ArgumentDocumentation(
+        identifier=identifier,
+        description=description,
+    )
+
+
+def extract_predicate_documentation(node: Node) -> PredicateDocumentation:
+    """
+    Extract a PredicateDocumentation from a node.
+
+    Args:
+        node: The node representing the predicate documentation.
+
+    Returns:
+        The created PredicateDocumentation.
+    """
+    captures = Queries.DOC_PREDICATE.captures(node)
+
+    identifier = get_capture_text(captures, "identifier", 0)
+
+    # For some reason the query does not return the arguments
+    # in the order they appear. So we order them by their start byte.
+    argument_nodes = captures.get("argument", [])
+    argument_nodes.sort(key=lambda n: n.start_byte)
+    arguments = [get_node_text(arg) for arg in argument_nodes]
+
+    explicit_docs_map = {}
+    for arg_node in captures.get("arg.documentation", []):
+        doc = extract_argument_documentation(arg_node)
+        explicit_docs_map[doc.identifier] = doc
+
+    final_arguments = []
+    for name in arguments:
+        if name in explicit_docs_map:
+            final_arguments.append(explicit_docs_map[name])
+        else:
+            final_arguments.append(ArgumentDocumentation(identifier=name, description=""))
+
+    description = (
+        get_node_text(captures["description"][0]).removeprefix("%*!").removesuffix("*%").strip()
+        if captures.get("description")
+        else ""
+    )
+
+    return PredicateDocumentation(
+        row=node.start_point.row,
+        content=get_node_text(node),
+        signature=f"{identifier}/{len(arguments)}",
+        description=description,
+        arguments=final_arguments,
+    )

mkdocstrings_handlers/asp/_internal/collect/load.py

@@ -0,0 +1,92 @@
+"""This module handles loading and parsing ASP documents."""
+
+import logging
+from collections import deque
+from pathlib import Path
+
+from mkdocstrings_handlers.asp._internal.collect.extractors import (
+    extract_bare_statement,
+    extract_block_comment,
+    extract_include,
+    extract_line_comment,
+    extract_predicate_documentation,
+    extract_show,
+    extract_statement,
+)
+from mkdocstrings_handlers.asp._internal.collect.syntax import NodeKind, get_parser
+from mkdocstrings_handlers.asp._internal.domain import Document, ShowStatus
+
+log = logging.getLogger(__name__)
+
+
+def load_documents(paths: list[Path]) -> list[Document]:
+    """
+    Load and parse multiple ASP documents from the given file paths.
+
+    Args:
+        paths: List of paths to ASP files.
+
+    Returns:
+        List of parsed Document objects.
+    """
+    parse_queue = deque(paths)
+    documents: dict[Path, Document] = {}
+    while parse_queue:
+        path = parse_queue.popleft()
+        if path.suffix != ".lp" or not path.is_file():
+            log.warning("skip file %s, not a valid ASP file.", path)
+            continue
+        document = load_document(path)
+        documents[path] = document
+        parse_queue.extend(include.path for include in document.includes if include.path not in documents)
+
+    return list(documents.values())
+
+
+def load_document(file_path: Path) -> Document:
+    """
+    Load and parse an ASP document from the given file path.
+
+    Args:
+        file_path: Path to the ASP file.
+
+    Returns:
+        The parsed Document object.
+    """
+    with open(file_path, "rb") as f:
+        source_bytes = f.read()
+
+    document = Document(path=file_path, content=source_bytes.decode("utf-8"))
+    tree = get_parser().parse(source_bytes)
+
+    for node in tree.root_node.children:
+        match NodeKind.from_grammar_name(node.grammar_name):
+            case NodeKind.RULE | NodeKind.INTEGRITY_CONSTRAINT:
+                statement = extract_statement(node)
+                document.statements.append(statement)
+            case NodeKind.LINE_COMMENT:
+                line_comment = extract_line_comment(node)
+                document.line_comments.append(line_comment)
+            case NodeKind.BLOCK_COMMENT:
+                block_comment = extract_block_comment(node)
+                document.block_comments.append(block_comment)
+            case NodeKind.INCLUDE:
+                include = extract_include(node, file_path)
+                document.includes.append(include)
+            case NodeKind.SHOW | NodeKind.SHOW_SIGNATURE | NodeKind.SHOW_TERM:
+                show = extract_show(node)
+                statement = extract_statement(node)
+
+                if show.predicate is not None and show.status == ShowStatus.PARTIAL:
+                    statement.provided_predicates.append(show.predicate)
+
+                document.shows.append(show)
+                document.statements.append(statement)
+            case NodeKind.DOC_COMMENT:
+                predicate_documentation = extract_predicate_documentation(node)
+                document.predicate_documentations.append(predicate_documentation)
+            case _:
+                statement = extract_bare_statement(node)
+                document.statements.append(statement)
+
+    return document

mkdocstrings_handlers/asp/_internal/collect/queries/body.scm

@@ -0,0 +1,11 @@
+; -----------------------------------------------------------------------------
+; This gathers needed predicates in the body of a statement
+; -----------------------------------------------------------------------------
+
+(body_literal
+    (symbolic_atom)
+) @needed
+
+(literal
+    (symbolic_atom)
+) @needed

mkdocstrings_handlers/asp/_internal/collect/queries/documentation_argument.scm

@@ -0,0 +1,4 @@
+(doc_arg
+    (variable) @identifier
+    (doc_desc)? @description
+)

mkdocstrings_handlers/asp/_internal/collect/queries/documentation_predicate.scm

@@ -0,0 +1,12 @@
+(doc_comment
+    (doc_predicate
+        (identifier) @identifier
+        (variables
+            (variable) @argument
+        )?
+    )
+    (doc_desc)? @description
+    (doc_args
+        (doc_arg) @arg.documentation
+    )?
+)