feat: better publishing workflow + tests

.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

README.md

@@ -26,7 +26,7 @@ py2fern write /path/to/your/package --output ./docs/api
 
 This creates:
 - **MDX files** with Fern-compatible frontmatter and slugs
-- **`navigation.yml`** for Fern docs structure 
+- **`navigation.yml`** for Fern docs structure
 
 ## Acknowledgments
 

pyproject.toml

@@ -20,7 +20,7 @@ urls = {Home = "https://github.com/fern-api/py2fern"}
 requires-python = ">=3.8"
 dependencies = [
     "astroid>=2.7,<4",
-    "tomli; python_version<'3.11'", 
+    "tomli; python_version<'3.11'",
     "typing-extensions",
     "typer[all]",
     "PyYAML"
@@ -31,6 +31,8 @@ testing = [
     "pytest",
     "pytest-regressions", 
     "pytest-cov",
+    "PyYAML",  # Needed for navigation YAML tests
+    "types-PyYAML",  # Type stubs for mypy
 ]
 
 [project.scripts]

src/autodoc2/__init__.py

@@ -3,4 +3,27 @@
 A simplified fork of sphinx-autodoc2 focused purely on Python → Fern markdown output.
 """
 
-__version__ = "0.1.1"
+import subprocess
+from pathlib import Path
+
+
+def _get_version() -> str:
+    """Get version from git tag or fallback to default."""
+    try:
+        if Path(".git").exists():
+            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

@@ -255,19 +255,20 @@ def _warn(msg: str, type_: WarningSubtypes) -> None:
             progress.console.print(f"[yellow]Warning[/yellow] {msg} [{type_.value}]")
 
         config = Config()
-        
+
         # Always use FernRenderer
         from autodoc2.render.fern_ import FernRenderer
+
         render_class = FernRenderer
-        
+
         for mod_name in to_write:
             progress.update(task, advance=1, description=mod_name)
             content = "\n".join(
                 render_class(db, config, warn=_warn).render_item(mod_name)
             )
-            
+
             # Use hyphens in filenames to match Fern slugs
-            filename = mod_name.replace('.', '-').replace('_', '-')
+            filename = mod_name.replace(".", "-").replace("_", "-")
             out_path = output / (filename + render_class.EXTENSION)
             paths.append(out_path)
             if out_path.exists() and out_path.read_text("utf8") == content:
@@ -283,6 +284,27 @@ 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]")

src/autodoc2/render/base.py

@@ -1,4 +1,5 @@
 """Convert the database items into documentation."""
+
 from __future__ import annotations
 
 import abc