📝 docs(api): add public docstrings

Author: philippb

sdiff/__init__.py

@@ -4,6 +4,17 @@
 
 
 def diff(md1, md2, renderer=TextRenderer(), parser_cls: type[MdParser] = MdParser):
+    """Compare two Markdown strings by structure and return rendered outputs + errors.
+
+    Args:
+        md1: Left Markdown string.
+        md2: Right Markdown string.
+        renderer: Renderer instance used to format the output (TextRenderer by default).
+        parser_cls: Parser class to use (MdParser by default).
+
+    Returns:
+        (rendered_left, rendered_right, errors)
+    """
     tree1 = parse(md1, parser_cls)
     tree2 = parse(md2, parser_cls)
 

sdiff/compare.py

@@ -44,8 +44,10 @@ def _diff(tree1, tree2, include_symbols=None, exclude_symbols=None):
 
 
 def diff_links(tree1, tree2):
+    """Diff only link-relevant structure (paragraphs/headers/lists/links)."""
     return _diff(tree1, tree2, include_symbols=['p', 'h', 'l', 'a'])
 
 
 def diff_struct(tree1, tree2):
+    """Diff overall structure, ignoring link and image content."""
     return _diff(tree1, tree2, exclude_symbols=['a', 'i'])

sdiff/parser.py

@@ -22,6 +22,10 @@
 
 
 class MdParser:
+    """Markdown parser that builds a lightweight structural tree.
+
+    Uses Mistune AST tokens to build sdiff Node objects.
+    """
     list_rules = None
 
     @classmethod
@@ -33,6 +37,15 @@ def __init__(self):
         self._reference_definitions = {}
 
     def parse(self, text, rules=None):
+        """Parse Markdown text into a list of Node objects.
+
+        Args:
+            text: Markdown string.
+            rules: Optional rules argument kept for compatibility.
+
+        Returns:
+            list[Node]
+        """
         tokens = self._markdown(text)
         return self._convert_block_tokens(tokens)
 
@@ -253,6 +266,7 @@ class ZendeskHelpMdParser(MdParser):
     _TABS_PATTERN = re.compile(r'(?s)<tabs>(?P<content>.*?)</tabs>')
 
     def parse(self, text, rules=None):
+        """Parse Markdown with Zendesk tag support into a list of Node objects."""
         nodes = self._parse_nodes(text)
         return nodes
 
@@ -425,6 +439,7 @@ def _remove_ltr_rtl_marks(text):
 
 
 def parse(text, parser_cls: type[MdParser] = MdParser):
+    """Parse Markdown into a Root node using the given parser class."""
     text = _remove_spaces_from_empty_lines(text)
     text = _remove_ltr_rtl_marks(text)
     parser = parser_cls()

sdiff/renderer.py

@@ -2,6 +2,7 @@
 
 
 class HtmlRenderer:
+    """Render a tree to HTML, marking inserts/deletes with ins/del tags."""
 
     def render(self, tree: Root):
         result = tree.original(self)
@@ -16,6 +17,7 @@ def render_node(self, node, text):
 
 
 class TextRenderer:
+    """Render a tree back to plain text/Markdown-like output."""
 
     def render(self, tree: Root):
         result = tree.original(self)