asciidocstring 0.1.0__tar.gz

asciidocstring-0.1.0/.agents/AGENTS.md

@@ -0,0 +1,63 @@
+# Agent Rules & Repository Guide: `asciidocstring`
+
+Welcome, fellow agent! This file contains critical context, guidelines, and rules for working with this repository.
+
+---
+
+## 1. Development Rules
+
+### Rule 1: Strict Red / Green TDD
+Always write focused, failing tests first in the `tests/` directory before writing or editing production code.
+* Verify the **RED** stage by running `PYTHONPATH=src venv/bin/pytest tests/`.
+* Write the minimum code required to go **GREEN**.
+* Keep the test suite passing throughout.
+
+### Rule 2: Pure Python and Portability
+We target **Python 3.14+** and **Pyodide (WASM) 314.0+**.
+* Do **NOT** add any dependencies with native C/C++ compiled extensions.
+* Ensure all code runs flawlessly in WASM environments.
+
+### Rule 3: Linting & Typing Standards
+Keep the codebase strictly clean and typed:
+* Run Ruff: `venv/bin/ruff check src/ tests/`
+* Run MyPy: `venv/bin/mypy src/`
+
+---
+
+## 2. Core Architecture
+
+The library processes Python docstrings written in AsciiDoc using a decoupled, two-stage architecture:
+
+1. **Parser & Cleaning Layer (`src/asciidocstring/document.py`):**
+   * Uses `inspect.cleandoc` to calculate and strip common leading whitespace from docstrings.
+   * Dynamically appends a trailing `\n` to inputs to avoid `lark.exceptions.UnexpectedEOF` (required by `asciidoctrine`).
+   * Parses the cleaned text into an Abstract Semantic Graph (ASG) using `asciidoctrine.lark_parser.parse_to_ast()`.
+
+2. **AST Processing & Visitors Layer (`src/asciidocstring/visitors.py`):**
+   * Subclasses `asciidoctrine.nodes.NodeVisitor`.
+   * For docstring rendering, serializes the AST to reStructuredText (`ReSTSerializerVisitor`).
+   * For doctests, queries and extracts executable code blocks (`TestBlockExtractorVisitor`).
+
+---
+
+## 3. Reference Commands
+
+```bash
+# Set up environment
+python3 -m venv venv
+venv/bin/pip install -e .
+
+# Run test suite
+PYTHONPATH=src venv/bin/pytest
+
+# Run static quality checks
+venv/bin/ruff check src/ tests/
+mypy src/
+```
+
+---
+
+## 4. Known Upstream Limitations & Parser Details
+
+* **Bare-URL Autolinks (Issue [#76](https://github.com/webmaven/asciidoctrine/issues/76)):** `asciidoctrine` does not yet parse bare URLs (such as `https://google.com` without bracketed labels) as `Ref` nodes; they are currently parsed as plain `Text` nodes. Use bracketed links `https://google.com[Google]` where explicit translation is required.
+

asciidocstring-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+bin/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing / coverage
+.cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# OS-specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

asciidocstring-0.1.0/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if distributed along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

asciidocstring-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: asciidocstring
+Version: 0.1.0
+Summary: A semantic parser and converter for Python docstrings written in AsciiDoc
+Project-URL: Homepage, https://github.com/webmaven/asciidocstring
+Author: webmaven
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: asciidoctrine>=0.1.0a3
+Requires-Dist: lark==1.3.1
+Description-Content-Type: text/plain
+
+= AsciiDocString
+:toc: left
+:sectnums:
+
+A semantic parser, extractor, and translator for Python docstrings written in AsciiDoc.
+
+== Introduction
+
+`asciidocstring` is a Python library built on top of the pure-Python `asciidoctrine` parser. It is designed to clean raw docstrings (stripping common indentation) and compile them into a structured Abstract Semantic Graph (ASG). 
+
+This parsed semantic graph can be used by downstream libraries to:
+1. Render high-fidelity reStructuredText for Sphinx (`sphinx-asciidoc`).
+2. Query and run interactive doctests (`asciidoctest`).
+
+== Installation
+
+[source,bash]
+----
+pip install asciidocstring
+----
+
+== Usage
+
+=== Parsing a Docstring
+
+[source,python]
+----
+import asciidocstring
+
+docstring = """
+    = Parse Coordinates
+    
+    This function processes dynamic coordinate objects.
+    
+    [source,python,test]
+    ----
+    assert parse_coords(10, 20) == (10, 20)
+    ----
+    
+    x (int):: The horizontal component
+    y (int):: The vertical component
+    """
+
+doc = asciidocstring.parse(docstring)
+
+# Convert to reStructuredText (reST) for Sphinx
+rest_output = doc.to_rest()
+
+# Extract code blocks for doctesting
+tests = doc.extract_tests()
+----
+
+== License
+
+This project is licensed under the Apache License, Version 2.0.

asciidocstring-0.1.0/README.adoc

@@ -0,0 +1,55 @@
+= AsciiDocString
+:toc: left
+:sectnums:
+
+A semantic parser, extractor, and translator for Python docstrings written in AsciiDoc.
+
+== Introduction
+
+`asciidocstring` is a Python library built on top of the pure-Python `asciidoctrine` parser. It is designed to clean raw docstrings (stripping common indentation) and compile them into a structured Abstract Semantic Graph (ASG). 
+
+This parsed semantic graph can be used by downstream libraries to:
+1. Render high-fidelity reStructuredText for Sphinx (`sphinx-asciidoc`).
+2. Query and run interactive doctests (`asciidoctest`).
+
+== Installation
+
+[source,bash]
+----
+pip install asciidocstring
+----
+
+== Usage
+
+=== Parsing a Docstring
+
+[source,python]
+----
+import asciidocstring
+
+docstring = """
+    = Parse Coordinates
+    
+    This function processes dynamic coordinate objects.
+    
+    [source,python,test]
+    ----
+    assert parse_coords(10, 20) == (10, 20)
+    ----
+    
+    x (int):: The horizontal component
+    y (int):: The vertical component
+    """
+
+doc = asciidocstring.parse(docstring)
+
+# Convert to reStructuredText (reST) for Sphinx
+rest_output = doc.to_rest()
+
+# Extract code blocks for doctesting
+tests = doc.extract_tests()
+----
+
+== License
+
+This project is licensed under the Apache License, Version 2.0.

asciidocstring-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "asciidocstring"
+dynamic = ["version"]
+description = "A semantic parser and converter for Python docstrings written in AsciiDoc"
+readme = { file = "README.adoc", content-type = "text/plain" }
+requires-python = ">=3.14"
+license = "Apache-2.0"
+authors = [
+    { name = "webmaven" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "asciidoctrine>=0.1.0a3",
+    "lark==1.3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/webmaven/asciidocstring"
+
+[tool.hatch.version]
+path = "src/asciidocstring/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/asciidocstring"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"  # Ruff supports target version up to current stable
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+warn_unreachable = true
+pretty = true

asciidocstring-0.1.0/src/asciidocstring/__init__.py

@@ -0,0 +1,5 @@
+from .document import AsciiDocStringDocument, parse
+from .visitors import TestBlock
+
+__version__ = "0.1.0"
+__all__ = ["parse", "AsciiDocStringDocument", "TestBlock"]

asciidocstring-0.1.0/src/asciidocstring/document.py

@@ -0,0 +1,47 @@
+import inspect
+from typing import Any, List
+
+from asciidoctrine.lark_parser import parse_to_ast
+
+from .visitors import ReSTSerializerVisitor, TestBlock, TestBlockExtractorVisitor
+
+
+class AsciiDocStringDocument:
+    """The main interface representing a parsed AsciiDoc docstring."""
+    
+    def __init__(self, raw_source: str):
+        self.raw_source = raw_source
+        self.clean_source = self._clean(raw_source)
+        self.ast = self._parse(self.clean_source)
+
+    def _clean(self, source: str) -> str:
+        """Strip common leading indentation and ensure a trailing newline."""
+        cleaned = inspect.cleandoc(source)
+        # Ensure a trailing newline to avoid lark EOF errors
+        if not cleaned.endswith("\n"):
+            cleaned += "\n"
+        return cleaned
+
+    def _parse(self, source: str) -> Any:
+        """Parse cleaned AsciiDoc using asciidoctrine's Lark parser."""
+        try:
+            return parse_to_ast(source)
+        except Exception as e:
+            # Re-raise standard parser errors transparently or wrap them if needed
+            raise ValueError(f"AsciiDoc Parse Error: {e}") from e
+
+    def to_rest(self) -> str:
+        """Render parsed ASG into standard reStructuredText."""
+        visitor = ReSTSerializerVisitor()
+        return visitor.serialize(self.ast)
+
+    def extract_tests(
+        self, language: str = "python", requires_test_marker: bool = False
+    ) -> List[TestBlock]:
+        """Extract executable code blocks from the parsed AST."""
+        visitor = TestBlockExtractorVisitor(language, requires_test_marker)
+        return visitor.extract(self.ast)
+
+def parse(docstring: str) -> AsciiDocStringDocument:
+    """Convenience function to parse a raw python docstring."""
+    return AsciiDocStringDocument(docstring)

asciidocstring-0.1.0/src/asciidocstring/visitors.py

@@ -0,0 +1,235 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List
+
+from asciidoctrine.nodes import Listing, NodeVisitor
+
+
+@dataclass
+class TestBlock:
+    """Represents an executable code block extracted from a docstring."""
+    content: str
+    language: str
+    line_number: int
+    is_interactive: bool  # True if it contains ">>> " style prompts
+    attributes: Dict[str, Any]
+
+class TestBlockExtractorVisitor(NodeVisitor):
+    """AST visitor to locate and extract Python test blocks from a docstring."""
+    
+    def __init__(self, target_language: str, requires_test_marker: bool):
+        self.target_language = target_language.lower()
+        self.requires_test_marker = requires_test_marker
+        self.extracted_tests: List[TestBlock] = []
+
+    def extract(self, node: Any) -> List[TestBlock]:
+        """Reset state, traverse the node tree, and return extracted test blocks."""
+        self.extracted_tests = []
+        self.visit(node)
+        return self.extracted_tests
+
+    def visit_listing(self, node: Listing) -> None:
+        """Process code listing blocks."""
+        attrs = node.attributes or {}
+        style = attrs.get("style", "")
+        lang = attrs.get("language", "").lower()
+        
+        # A Listing node with style='source' represents a source code block
+        is_source = (style == "source" or node.name == "listing")
+        is_target_lang = (lang == self.target_language) or (
+            not lang and self.target_language == "python"
+        )
+        
+        # Sgthand [.test] parsed as 'role': 'test', or positional [source,python,test]
+        has_test_marker = (
+            "test" in attrs
+            or attrs.get("role") == "test"
+            or attrs.get("3") == "test"
+            or "test" in attrs.get("positional", [])
+        )
+        
+        if is_source and is_target_lang:
+            if self.requires_test_marker and not has_test_marker:
+                return  # Skip since test marker is required but not present
+                
+            # Extract content from Text inline nodes
+            content_parts = [
+                inline.value
+                for inline in node.inlines
+                if hasattr(inline, "value")
+            ]
+            content = "".join(content_parts)
+            
+            # Identify interactive session
+            is_interactive = ">>> " in content
+            
+            # Fetch line numbers from node locations if available
+            line_number = 1
+            if hasattr(node, "location") and node.location:
+                line_number = node.location[0].get("line", 1)
+                
+            self.extracted_tests.append(TestBlock(
+                content=content,
+                language=lang or self.target_language,
+                line_number=line_number,
+                is_interactive=is_interactive,
+                attributes=attrs
+            ))
+
+class ReSTSerializerVisitor(NodeVisitor):
+    """AST visitor to serialize parsed AsciiDoc to reStructuredText."""
+    
+    def __init__(self) -> None:
+        self.output: List[str] = []
+        self._indent_level = 0
+        self._current_list_depth = 0
+
+    def serialize(self, node: Any) -> str:
+        """Reset state, walk AST, and return reST representation."""
+        self.output = []
+        self._indent_level = 0
+        self._current_list_depth = 0
+        self.visit(node)
+        # Strip excess trailing newlines from end of document
+        return "".join(self.output).rstrip() + "\n"
+
+    def render_inline(self, node: Any) -> str:
+        """Recursively render inline nodes and format their styles."""
+        if node.name == "text":
+            return str(node.value)
+        elif node.name == "span":
+            content = "".join(self.render_inline(sub) for sub in node.inlines)
+            if node.variant == "strong":
+                return f"**{content}**"
+            elif node.variant == "emphasis":
+                return f"*{content}*"
+            elif node.variant == "code":
+                return f"``{content}``"
+            return content
+        elif node.name == "ref":
+            content = "".join(self.render_inline(sub) for sub in node.inlines)
+            target = getattr(node, "target", "")
+            return f"`{content} <{target}>`_"
+        return ""
+
+    def visit_document(self, node: Any) -> None:
+        """Render Document header title and traverse block content."""
+        if hasattr(node, "header") and node.header and node.header.title:
+            title_text = "".join(
+                self.render_inline(inline)
+                for inline in node.header.title.inlines
+            )
+            underline = "=" * len(title_text)
+            self.output.append(f"{title_text}\n{underline}\n\n")
+            
+        for block in node.blocks:
+            self.visit(block)
+
+    def visit_section(self, node: Any) -> None:
+        """Render Section title with standard depth-based underline indicators."""
+        level = getattr(node, "level", 1)
+        # Underline character mapping: depth 0 is Document (=), depth 1 is Section (-)
+        char_map = {0: "=", 1: "-", 2: "~", 3: "^"}
+        underline_char = char_map.get(level, "-")
+        
+        if node.title:
+            title_text = "".join(
+                self.render_inline(inline) for inline in node.title.inlines
+            )
+            underline = underline_char * len(title_text)
+            self.output.append(f"{title_text}\n{underline}\n\n")
+            
+        for block in node.blocks:
+            self.visit(block)
+
+    def visit_paragraph(self, node: Any) -> None:
+        """Render a plain paragraph with the current block level indentation."""
+        content = "".join(self.render_inline(inline) for inline in node.inlines)
+        indent = " " * self._indent_level
+        self.output.append(f"{indent}{content}\n\n")
+
+    def visit_listing(self, node: Any) -> None:
+        """Render code block listing using Sphinx-standard code-block directives."""
+        attrs = node.attributes or {}
+        lang = attrs.get("language", "python")
+        
+        content_parts = [
+            inline.value for inline in node.inlines if hasattr(inline, "value")
+        ]
+        content = "".join(content_parts)
+        
+        indent = " " * self._indent_level
+        self.output.append(f"{indent}.. code-block:: {lang}\n\n")
+        
+        body_indent = " " * (self._indent_level + 3)
+        indented_lines = []
+        for line in content.splitlines():
+            if line.strip():
+                indented_lines.append(f"{body_indent}{line}")
+            else:
+                indented_lines.append("")
+        body = "\n".join(indented_lines)
+        self.output.append(f"{body}\n\n")
+
+    def visit_list(self, node: Any) -> None:
+        """Render bullets and handle list level nesting contexts."""
+        old_depth = self._current_list_depth
+        self._current_list_depth += 1
+        
+        for item in node.items:
+            self.visit(item)
+            
+        self._current_list_depth = old_depth
+
+    def visit_listitem(self, node: Any) -> None:
+        """Render standard bullet item formatting."""
+        indent_size = (self._current_list_depth - 1) * 2
+        indent = " " * indent_size
+        
+        content = ""
+        if hasattr(node, "principal") and node.principal:
+            content = "".join(self.render_inline(inline) for inline in node.principal)
+            
+        self.output.append(f"{indent}* {content}\n")
+        
+        # Render nested block children under this item
+        old_indent = self._indent_level
+        self._indent_level += indent_size + 2
+        for block in node.blocks:
+            self.visit(block)
+        self._indent_level = old_indent
+
+    def visit_descriptionlist(self, node: Any) -> None:
+        """Render description lists."""
+        for item in node.items:
+            self.visit(item)
+
+    def visit_descriptionlistitem(self, node: Any) -> None:
+        """Render a single description list item (definition)."""
+        for term in node.terms:
+            term_text = "".join(self.render_inline(inline) for inline in term.inlines)
+            self.output.append(f"{term_text}\n")
+            
+        old_indent = self._indent_level
+        # reST standard definition block is indented by 3 spaces
+        self._indent_level += 3
+        for block in node.blocks:
+            self.visit(block)
+        self._indent_level = old_indent
+
+    def visit_admonition(self, node: Any) -> None:
+        """Render standard admonition blocks (e.g. note, warning, tip)."""
+        variant = getattr(node, "variant", "note").lower()
+        
+        indent = " " * self._indent_level
+        self.output.append(f"{indent}.. {variant}::\n\n")
+        
+        old_indent = self._indent_level
+        self._indent_level += 3
+        for block in node.blocks:
+            self.visit(block)
+        self._indent_level = old_indent
+
+    def visit_thematicbreak(self, node: Any) -> None:
+        """Render thematic breaks (horizontal lines)."""
+        indent = " " * self._indent_level
+        self.output.append(f"{indent}----\n\n")

asciidocstring-0.1.0/tests/test_extractor.py

@@ -0,0 +1,82 @@
+import asciidocstring
+
+
+def test_extract_python_source_blocks() -> None:
+    # Docstring with python source block and other language
+    docstring = """
+        Some introduction text.
+        
+        [source,python]
+        ----
+        assert foo() == 42
+        ----
+        
+        And some Ruby code that should be ignored by default:
+        [source,ruby]
+        ----
+        foo = 42
+        ----
+        """
+    doc = asciidocstring.parse(docstring)
+    tests = doc.extract_tests(language="python")
+    
+    assert len(tests) == 1
+    test_block = tests[0]
+    
+    # Assert fields are extracted correctly
+    assert test_block.content.strip() == "assert foo() == 42"
+    assert test_block.language == "python"
+    assert test_block.is_interactive is False
+    assert test_block.line_number > 1  # Should find starting line number of block
+
+def test_extract_interactive_prompts() -> None:
+    # Docstring with standard python interactive prompts
+    docstring = """
+        [source,python]
+        ----
+        >>> foo()
+        42
+        ----
+        """
+    doc = asciidocstring.parse(docstring)
+    tests = doc.extract_tests(language="python")
+    
+    assert len(tests) == 1
+    assert tests[0].is_interactive is True
+
+def test_requires_test_marker_filter() -> None:
+    # Docstring containing both a normal source block and different
+    # test-marked source blocks
+    docstring = """
+        A non-test block:
+        [source,python]
+        ----
+        x = 1
+        ----
+        
+        A test block with consecutive independent attribute lines:
+        # (merged role + source)
+        [.test]
+        [source,python]
+        ----
+        y = 2
+        ----
+        
+        A test block with positional third attribute [source,python,test]:
+        [source,python,test]
+        ----
+        z = 3
+        ----
+        """
+    doc = asciidocstring.parse(docstring)
+    
+    # By default, extracting tests should not require explicit marker
+    all_tests = doc.extract_tests(requires_test_marker=False)
+    assert len(all_tests) == 3
+    
+    # When requires_test_marker is True, only return blocks with "test" marker
+    explicit_tests = doc.extract_tests(requires_test_marker=True)
+    assert len(explicit_tests) == 2
+    
+    contents = {b.content.strip() for b in explicit_tests}
+    assert contents == {"y = 2", "z = 3"}

asciidocstring-0.1.0/tests/test_parser.py

@@ -0,0 +1,40 @@
+import pytest
+
+import asciidocstring
+from asciidocstring.document import AsciiDocStringDocument
+
+
+def test_indentation_stripping() -> None:
+    # A standard raw indented docstring
+    raw_docstring = """
+        = Sample Docstring
+        
+        This is a paragraph under the docstring.
+        It should have common indentation stripped.
+        """
+    doc = asciidocstring.parse(raw_docstring)
+    assert isinstance(doc, AsciiDocStringDocument)
+    # The clean source should be normalized without common leading whitespace
+    expected = (
+        "= Sample Docstring\n\n"
+        "This is a paragraph under the docstring.\n"
+        "It should have common indentation stripped.\n"
+    )
+    assert doc.clean_source == expected
+
+def test_unexpected_eof_prevention() -> None:
+    # Under the hood, lark will fail on string ends without a trailing newline
+    # asciidocstring should ensure a trailing newline is appended
+    no_newline = "== Section Header"
+    doc = asciidocstring.parse(no_newline)
+    assert doc.clean_source == "== Section Header\n"
+    assert doc.ast is not None
+
+def test_strict_parsing_errors() -> None:
+    # Testing that syntactically invalid input raises descriptive errors
+    invalid_syntax = ":: invalid\n"
+    with pytest.raises(Exception) as exc_info:
+         asciidocstring.parse(invalid_syntax)
+    # Check that it raised our custom parse exception with context details
+    assert "Parse Error" in str(exc_info.value)
+

asciidocstring-0.1.0/tests/test_renderer.py

@@ -0,0 +1,98 @@
+import asciidocstring
+
+
+def test_basic_blocks_serialization() -> None:
+    docstring = """
+        = Document Title
+        
+        This is a plain paragraph.
+        
+        == Section Subtitle
+        
+        Another paragraph.
+        """
+    doc = asciidocstring.parse(docstring)
+    rest = doc.to_rest()
+    
+    # Assert titles are translated to proper reST underlines
+    assert "Document Title\n==============" in rest
+    assert "Section Subtitle\n----------------" in rest
+    assert "This is a plain paragraph." in rest
+
+def test_source_listing_serialization() -> None:
+    docstring = """
+        Here is some code:
+        
+        [source,python]
+        ----
+        x = 42
+        print(x)
+        ----
+        """
+    doc = asciidocstring.parse(docstring)
+    rest = doc.to_rest()
+    
+    expected_block = ".. code-block:: python\n\n   x = 42\n   print(x)"
+    assert expected_block in rest
+
+def test_inline_formatting_serialization() -> None:
+    docstring = """
+        This text contains *bold word*, _italic word_, and `monospace code`.
+        """
+    doc = asciidocstring.parse(docstring)
+    rest = doc.to_rest()
+    
+    # Bold *x* in AsciiDoc -> **x** in reST
+    # Italic _x* in AsciiDoc -> *x* in reST
+    # Monospace `x` in AsciiDoc -> ``x`` in reST
+    assert "contains **bold word**," in rest
+    assert "*italic word*," in rest
+    assert "``monospace code``." in rest
+
+def test_lists_serialization() -> None:
+    docstring = """
+        * First bullet
+        * Second bullet
+        ** Nested bullet
+        """
+    doc = asciidocstring.parse(docstring)
+    rest = doc.to_rest()
+    
+    # Assert standard bullet formatting and indentation
+    assert "* First bullet" in rest
+    assert "  * Nested bullet" in rest
+
+def test_description_lists_serialization() -> None:
+    docstring = """
+        param1 (int):: The first parameter
+        param2 (str):: The second parameter
+        """
+    doc = asciidocstring.parse(docstring)
+    rest = doc.to_rest()
+    
+    expected_param1 = "param1 (int)\n   The first parameter"
+    expected_param2 = "param2 (str)\n   The second parameter"
+    assert expected_param1 in rest
+    assert expected_param2 in rest
+
+def test_admonitions_serialization() -> None:
+    docstring = """
+        WARNING: This is a warning message.
+        """
+    doc = asciidocstring.parse(docstring)
+    rest = doc.to_rest()
+    
+    expected_admonition = ".. warning::\n\n   This is a warning message."
+    assert expected_admonition in rest
+
+def test_links_serialization() -> None:
+    docstring = """
+        Check out http://example.com[Example Site] for more details.
+        """
+    doc = asciidocstring.parse(docstring)
+    rest = doc.to_rest()
+    
+    expected_link = "Check out `Example Site <http://example.com>`_ for more details."
+    assert expected_link in rest
+
+