tests

Author: Ryan-Amirthan

.github/workflows/main.yml

@@ -76,16 +76,19 @@ jobs:
     steps:
     - name: Checkout source
       uses: actions/checkout@v4
-    - name: Set up Python 3.8
+      with:
+        fetch-depth: 0
+    - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
-        python-version: "3.8"
-    - name: install flit
+        python-version: "3.11"
+    - name: Install flit
+      run: pip install flit
+    - name: Verify version
       run: |
-        pip install flit~=3.4
+        python -c "from src.autodoc2 import __version__; print(f'Publishing version: {__version__}')"
     - name: Build and publish
-      run: |
-        flit publish
+      run: flit publish
       env:
         FLIT_USERNAME: __token__
-        FLIT_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        FLIT_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -153,3 +153,5 @@ cython_debug/
 .vscode/
 docs/_build/
 _autodoc/
+
+**/.DS_Store

src/autodoc2/__init__.py

@@ -3,4 +3,23 @@
 A simplified fork of sphinx-autodoc2 focused purely on Python → Fern markdown output.
 """
 
-__version__ = "0.1.1"
+import subprocess
+import os
+
+def _get_version():
+    """Get version from git tag or fallback to default."""
+    try:
+        if os.path.exists('.git'):
+            result = subprocess.run(
+                ['git', 'describe', '--tags', '--exact-match', 'HEAD'],
+                capture_output=True, text=True, check=True
+            )
+            version = result.stdout.strip()
+            return version[1:] if version.startswith('v') else version
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+    
+    # Fallback version for development
+    return "0.1.2-dev"
+
+__version__ = _get_version()

src/autodoc2/cli.py

@@ -283,6 +283,23 @@ def _warn(msg: str, type_: WarningSubtypes) -> None:
     nav_path.write_text(nav_content, "utf8")
     console.print(f"Navigation written to: {nav_path}")
 
+    # Validate all links
+    console.print("[bold]Validating links...[/bold]")
+    validation_results = renderer_instance.validate_all_links(str(output))
+    
+    if validation_results["errors"]:
+        console.print(f"[red]❌ {len(validation_results['errors'])} link errors found:[/red]")
+        for error in validation_results["errors"]:
+            console.print(f"  [red]• {error}[/red]")
+    
+    if validation_results["warnings"]:
+        console.print(f"[yellow]⚠️  {len(validation_results['warnings'])} link warnings:[/yellow]")
+        for warning in validation_results["warnings"]:
+            console.print(f"  [yellow]• {warning}[/yellow]")
+    
+    if not validation_results["errors"] and not validation_results["warnings"]:
+        console.print("[green]✅ All links validated successfully![/green]")
+
     # remove any files that are no longer needed
     if clean:
         console.print("[bold]Cleaning old files[/bold]")

tests/test_render.py

@@ -2,6 +2,8 @@
 
 from pathlib import Path
 from textwrap import dedent
+import yaml
+import re
 
 from autodoc2.analysis import analyse_module
 from autodoc2.config import Config
@@ -12,26 +14,243 @@
 
 
 def test_basic(tmp_path: Path, file_regression):
-    """Test basic rendering."""
+    """Test basic rendering - minimal snapshot test for regression detection."""
     package = build_package(tmp_path)
     db = InMemoryDb()
     for path, modname in yield_modules(package):
         for item in analyse_module(path, modname):
             db.add(item)
     content = "\n".join(FernRenderer(db, Config()).render_item(package.name))
-    file_regression.check(content, extension=".md")
+    file_regression.check(content, extension=".mdx")
 
 
-def test_config_options(tmp_path: Path, file_regression):
-    """Test basic rendering."""
+def test_link_validation(tmp_path: Path):
+    """Test that all generated links are valid and follow correct patterns."""
     package = build_package(tmp_path)
     db = InMemoryDb()
     for path, modname in yield_modules(package):
         for item in analyse_module(path, modname):
             db.add(item)
+    
+    renderer = FernRenderer(db, Config())
+    
+    # Test link validation method works (if available)
+    if hasattr(renderer, 'validate_all_links'):
+        validation_results = renderer.validate_all_links()
+        assert isinstance(validation_results, dict), "validate_all_links should return dict"
+        assert "errors" in validation_results, "Should have errors key"
+        assert "warnings" in validation_results, "Should have warnings key"
+        assert isinstance(validation_results["errors"], list), "Errors should be list"
+        assert isinstance(validation_results["warnings"], list), "Warnings should be list"
+        
+        # Should have no errors on our test package
+        assert not validation_results["errors"], f"Found link errors: {validation_results['errors']}"
+    
+    # Test specific link patterns in rendered content
+    content = "\n".join(renderer.render_item(package.name))
+    
+    # Check for same-page anchor links (items within same package)
+    assert re.search(r'\[`\w+`\]\(#\w+\)', content), "Should have same-page anchor links"
+    
+    # Check for cross-page links (subpackages/submodules)
+    if "package-a" in content:
+        assert re.search(r'\[`\w+`\]\([\w-]+\)', content), "Should have cross-page links"
+
+
+def test_anchor_generation(tmp_path: Path):
+    """Test that anchor IDs are generated correctly."""
+    package = build_package(tmp_path)
+    db = InMemoryDb()
+    for path, modname in yield_modules(package):
+        for item in analyse_module(path, modname):
+            db.add(item)
+    
+    renderer = FernRenderer(db, Config())
+    content = "\n".join(renderer.render_item(package.name))
+    
+    # Test that anchors exist in the rendered content
+    # Look for anchor patterns like #packageclass, #packagefunc 
+    assert re.search(r'#package\w+', content), "Should have anchor links with package prefix"
+    
+    # Test that rendered content has some consistent anchor pattern
+    anchor_matches = re.findall(r'\(#(\w+)\)', content)
+    assert len(anchor_matches) > 0, "Should have at least one anchor link"
+    
+    # Anchors should be lowercase and contain no dots or special chars
+    for anchor in anchor_matches:
+        assert anchor.islower(), f"Anchor should be lowercase: {anchor}"
+        assert '.' not in anchor, f"Anchor should not contain dots: {anchor}"
+
+
+def test_cross_reference_linking(tmp_path: Path):
+    """Test that cross-reference links work correctly with context awareness."""
+    package = build_package(tmp_path)
+    db = InMemoryDb()
+    for path, modname in yield_modules(package):
+        for item in analyse_module(path, modname):
+            db.add(item)
+    
+    renderer = FernRenderer(db, Config())
+    content = "\n".join(renderer.render_item(package.name))
+    
+    # Test that we have both types of links
+    # Same-page links (just anchor): [`Class`](#packageclass)
+    same_page_links = re.findall(r'\[`\w+`\]\(#\w+\)', content)
+    assert len(same_page_links) > 0, "Should have same-page anchor links"
+    
+    # Cross-page links (page + anchor): [`submod`](package-submod#anchor) 
+    cross_page_links = re.findall(r'\[`\w+`\]\([\w-]+(?:#\w+)?\)', content)
+    # Note: cross-page links may or may not have anchors depending on target type
+    
+    # Test link format consistency
+    for link in same_page_links:
+        # Should start with backticks and have # anchor
+        assert link.startswith('[`') and ')' in link and '#' in link, f"Malformed same-page link: {link}"
+    
+    # Test that items in summary tables link correctly
+    # Classes and functions should link to their anchors on the same page
+    class_item = renderer.get_item("package.Class")
+    func_item = renderer.get_item("package.func")
+    
+    if class_item:
+        # Should find Class linked with an anchor in the content
+        assert re.search(r'\[`Class`\]\(#package\w*class\w*\)', content), "Class should be linked with anchor"
+    
+    if func_item:
+        # Should find func linked with an anchor in the content
+        assert re.search(r'\[`func`\]\(#package\w*func\w*\)', content), "Function should be linked with anchor"
+
+
+def test_rendering_pipeline(tmp_path: Path):
+    """Test that the full rendering pipeline works without crashes."""
+    package = build_package(tmp_path)
+    db = InMemoryDb()
+    for path, modname in yield_modules(package):
+        for item in analyse_module(path, modname):
+            db.add(item)
+    
+    renderer = FernRenderer(db, Config())
+    
+    # Test each item type can be rendered without crashes
+    for item_type in ["package", "module", "class", "function", "data"]:
+        items = list(db.get_by_type(item_type))
+        if items:
+            item = items[0]
+            try:
+                content_lines = list(renderer.render_item(item["full_name"]))
+                assert content_lines, f"Empty output for {item_type}: {item['full_name']}"
+                content = "\n".join(content_lines)
+                assert len(content) > 10, f"Suspiciously short content for {item_type}"
+            except Exception as e:
+                pytest.fail(f"Rendering {item_type} {item['full_name']} crashed: {e}")
+
+
+def test_frontmatter_structure(tmp_path: Path):
+    """Test that frontmatter is generated correctly."""
+    package = build_package(tmp_path)
+    db = InMemoryDb()
+    for path, modname in yield_modules(package):
+        for item in analyse_module(path, modname):
+            db.add(item)
+    
+    renderer = FernRenderer(db, Config())
+    content = "\n".join(renderer.render_item(package.name))
+    
+    # Should start with frontmatter
+    assert content.startswith("---\n"), "Content should start with frontmatter"
+    
+    # Extract frontmatter
+    parts = content.split("---\n")
+    assert len(parts) >= 3, "Should have opening ---, frontmatter, closing ---, content"
+    
+    frontmatter = parts[1].strip()
+    assert frontmatter, "Frontmatter should not be empty"
+    
+    # Parse as valid YAML
+    try:
+        fm_data = yaml.safe_load(frontmatter)
+        assert isinstance(fm_data, dict), "Frontmatter should be valid YAML dict"
+        assert "layout" in fm_data, "Should have layout field"
+        assert "slug" in fm_data, "Should have slug field"
+        assert fm_data["layout"] == "overview", "Layout should be overview"
+    except yaml.YAMLError as e:
+        pytest.fail(f"Invalid frontmatter YAML: {e}")
+
+
+def test_code_block_structure(tmp_path: Path):
+    """Test that code blocks are properly formatted and closed."""
+    package = build_package(tmp_path)
+    db = InMemoryDb()
+    for path, modname in yield_modules(package):
+        for item in analyse_module(path, modname):
+            db.add(item)
+    
+    renderer = FernRenderer(db, Config())
+    content = "\n".join(renderer.render_item(package.name))
+    
+    # Count code block delimiters
+    python_blocks = content.count("```python")
+    closing_blocks = content.count("```\n") + content.count("```</CodeBlock>")
+    
+    assert python_blocks > 0, "Should have at least one Python code block"
+    assert python_blocks <= closing_blocks, f"Unmatched code blocks: {python_blocks} opening, {closing_blocks} closing"
+    
+    # Check for proper code block content
+    assert "def " in content or "class " in content, "Should have function or class definitions in code blocks"
+
+
+def test_navigation_generation(tmp_path: Path):
+    """Test that navigation.yml is generated correctly."""
+    package = build_package(tmp_path)
+    db = InMemoryDb()
+    for path, modname in yield_modules(package):
+        for item in analyse_module(path, modname):
+            db.add(item)
+    
+    renderer = FernRenderer(db, Config())
+    nav_yaml = renderer.generate_navigation_yaml()
+    
+    assert nav_yaml, "Navigation YAML should not be empty"
+    
+    # Parse as valid YAML
+    try:
+        nav_data = yaml.safe_load(nav_yaml)
+        assert isinstance(nav_data, dict), "Navigation should be a dict with 'navigation' key"
+        assert "navigation" in nav_data, "Should have 'navigation' key"
+        
+        nav_list = nav_data["navigation"]
+        assert isinstance(nav_list, list), "Navigation value should be a list"
+        assert len(nav_list) > 0, "Navigation should have at least one item"
+        
+        # Check structure of navigation items  
+        for item in nav_list:
+            assert isinstance(item, dict), "Navigation items should be dicts"
+            # Navigation can have 'section' or 'page' entries
+            assert "section" in item or "page" in item, f"Navigation item missing 'section' or 'page': {item}"
+            
+    except yaml.YAMLError as e:
+        pytest.fail(f"Invalid navigation YAML: {e}")
+
+
+def test_config_options_functional(tmp_path: Path):
+    """Test that config options work correctly (functional test, not snapshot)."""
+    package = build_package(tmp_path)
+    db = InMemoryDb()
+    for path, modname in yield_modules(package):
+        for item in analyse_module(path, modname):
+            db.add(item)
+    
+    # Test with no_index=True
     config = Config(no_index=True)
-    content = "\n".join(FernRenderer(db, config).render_item(package.name + ".func"))
-    file_regression.check(content, extension=".md")
+    renderer = FernRenderer(db, config)
+    
+    func_content = "\n".join(renderer.render_item(package.name + ".func"))
+    assert func_content, "Should render function content"
+    assert "```python" in func_content, "Should contain code block"
+    assert "This is a function" in func_content, "Should contain docstring"
+    
+    # Test basic rendering works
+    assert len(func_content.split('\n')) > 3, "Should have multiple lines of content"