Merge pull request #5 from fern-api/navigation

feat: Navigation

Author: Ryan-Amirthan

README.md

@@ -1,67 +1,28 @@
-# sphinx-autodoc-fern
+# sphinx-autodoc2-fern
 
-`sphinx-autodoc-fern` is a Sphinx extension that automatically generates API documentation for your Python packages with **Fern documentation format support**.
+Generate Fern-compatible API documentation from Python packages using static analysis.
 
-This is a fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) that adds powerful [Fern](https://buildwithfern.com) documentation generation capabilities.
+Fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) with [Fern](https://buildwithfern.com) output support.
 
-## 🆕 New Fern Features
-
-- **Fern-compatible Markdown output** - Generate documentation that works seamlessly with Fern
-- **Enhanced parameter formatting** - Uses Fern's ParamField components for better API documentation
-- **Smart callout handling** - Automatically converts NOTE: and WARNING: to Fern components
-- **Beautiful tables** - Improved formatting for classes, functions, and module contents
-
-Static analysis of Python code
-
-: There is no need to install your package to generate the documentation, and `sphinx-autodoc2` will correctly handle `if TYPE_CHECKING` blocks and other typing only features.
-: You can even document packages from outside the project (via `git clone`)!
-
-Optimized for rebuilds
-
-: Analysis of packages and file rendering are cached, so you can use `sphinx-autodoc2` in your development workflow.
-
-Support for `__all__`
-
-: `sphinx-autodoc2` can follow `__all__` variable, to only document the public API.
-
-Support for both `rst` and `md` docstrings
-
-: `sphinx-autodoc2` supports both `rst` and `md` ([MyST](https://myst-parser.readthedocs.io)) docstrings, which can be mixed within the same project.
-
-Highly configurable
-
-: `sphinx-autodoc-fern` is highly configurable, with many options to control the analysis and output of the documentation.
-
-Fern Documentation Format Support
-
-: Generate beautiful Fern-compatible documentation with enhanced formatting for parameters, callouts, and API references.
-
-Decoupled analysis and rendering
-
-: The analysis and rendering of the documentation are decoupled, and not dependent on Sphinx.
-: This means that you can use `sphinx-autodoc-fern` to generate documentation outside of Sphinx (see the `autodoc2` command line tool).
-
-## 🚀 Quick Start with Fern
+## Installation
 
 ```bash
-pip install sphinx-autodoc-fern
+pip install sphinx-autodoc2-fern
 ```
 
-To use the Fern renderer:
-
-```python
-from autodoc2.render.fern_ import FernRenderer
+## Usage
 
-renderer = FernRenderer()
-# Generate Fern-compatible documentation
-```
-
-Or use with the CLI:
+Generate Fern-compatible markdown documentation:
 
 ```bash
-autodoc2 --renderer fern your_package/
+autodoc2 --renderer fern /path/to/your/package
 ```
 
+This creates:
+- Markdown files with Fern-compatible frontmatter and slugs
+- `navigation.yml` for Fern docs structure
+- Tables with proper linking and descriptions
+
 ## Acknowledgments
 
 This project is a fork of the excellent [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) by Chris Sewell. All credit for the core functionality goes to the original project.

src/autodoc2/__init__.py

@@ -3,7 +3,7 @@
 This is a fork of sphinx-autodoc2 with added support for Fern documentation format.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 
 def setup(app):  # type: ignore

src/autodoc2/cli.py

@@ -276,7 +276,13 @@ def _warn(msg: str, type_: WarningSubtypes) -> None:
             content = "\n".join(
                 render_class(db, config, warn=_warn).render_item(mod_name)
             )
-            out_path = output / (mod_name + render_class.EXTENSION)
+            
+            # Use hyphens in filenames for Fern renderer to match slugs
+            if renderer == "fern":
+                filename = mod_name.replace('.', '-').replace('_', '-')
+                out_path = output / (filename + render_class.EXTENSION)
+            else:
+                out_path = output / (mod_name + render_class.EXTENSION)
             paths.append(out_path)
             if out_path.exists() and out_path.read_text("utf8") == content:
                 # Don't write the file if it hasn't changed

src/autodoc2/render/fern_.py

@@ -31,6 +31,8 @@ def render_item(self, full_name: str) -> t.Iterable[str]:
         if type_ in ("package", "module"):
             yield "---"
             yield "layout: overview"
+            slug = self._generate_slug(full_name)
+            yield f"slug: {slug}"
             yield "---"
             yield ""
 
@@ -137,35 +139,25 @@ def render_package(self, item: ItemData) -> t.Iterable[str]:
             yield ""
             for child in children_by_type["package"]:
                 name = child["full_name"].split(".")[-1]
-                # Create simple relative link using just the child name
-                link_path = name
+                # Create slug-based link using full dotted name
+                slug = self._generate_slug(child["full_name"])
                 doc_summary = child.get('doc', '').split('\n')[0][:80] if child.get('doc') else ""
                 if len(child.get('doc', '')) > 80:
                     doc_summary += "..."
-                yield f"- **[`{name}`]({link_path})** - {doc_summary}" if doc_summary else f"- **[`{name}`]({link_path})**"
+                yield f"- **[`{name}`]({slug})** - {doc_summary}" if doc_summary else f"- **[`{name}`]({slug})**"
             yield ""
 
         if has_submodules:
             yield "## Submodules" 
             yield ""
             for child in children_by_type["module"]:
                 name = child["full_name"].split(".")[-1]
-                # Replace underscores with dashes in display text for better readability
-                display_name = name.replace('_', '-')
-                
-                # Create contextual link based on current page
-                current_parts = item["full_name"].split(".")
-                if len(current_parts) == 1:
-                    # On root page - use simple name
-                    link_path = display_name
-                else:
-                    # On subpackage page - use full filename (convert dots and underscores to dashes)
-                    link_path = child["full_name"].replace('.', '-').replace('_', '-')
-                    
+                # Create slug-based link using full dotted name
+                slug = self._generate_slug(child["full_name"])
                 doc_summary = child.get('doc', '').split('\n')[0][:80] if child.get('doc') else ""
                 if len(child.get('doc', '')) > 80:
                     doc_summary += "..."
-                yield f"- **[`{display_name}`]({link_path})** - {doc_summary}" if doc_summary else f"- **[`{display_name}`]({link_path})**"
+                yield f"- **[`{name}`]({slug})** - {doc_summary}" if doc_summary else f"- **[`{name}`]({slug})**"
             yield ""
 
         # Show Module Contents summary if we have actual content (not just submodules)
@@ -530,10 +522,11 @@ def _format_docstring_sections(self, docstring: str, item: ItemData | None = Non
 
         # Parameters section
         if sections["parameters"]:
-            yield "**Parameters:**"
-            yield ""
             # If we have function item data, use ParamField components
             if item and item.get("args"):
+                yield "**Parameters:**"
+                yield ""
+                
                 # Build parameter info map from function signature
                 param_info = {}
                 for prefix, name, annotation, default in item["args"]:
@@ -711,4 +704,82 @@ def replace_tag(match):
             escaped_tag = tag.replace('{', '\\{').replace('}', '\\}')
             escaped_content = escaped_content.replace(placeholder, f'`{escaped_tag}`')
 
-        return escaped_content
+        return escaped_content
+
+    def _generate_slug(self, full_name: str) -> str:
+        """Generate slug from full dotted name: nemo_curator.utils.grouping → nemo-curator-utils-grouping"""
+        return full_name.replace('.', '-').replace('_', '-')
+
+    def generate_navigation_yaml(self) -> str:
+        """Generate navigation YAML for Fern docs.yml following sphinx autodoc2 toctree logic."""
+        import yaml
+        
+        # Find root packages (no dots in name)
+        root_packages = []
+        for item in self._db.get_by_type("package"):
+            full_name = item["full_name"]
+            if "." not in full_name:  # Root packages only
+                root_packages.append(item)
+        
+        if not root_packages:
+            return ""
+        
+        # Build navigation structure recursively
+        nav_contents = []
+        for root_pkg in sorted(root_packages, key=lambda x: x["full_name"]):
+            nav_item = self._build_nav_item_recursive(root_pkg)
+            if nav_item:
+                nav_contents.append(nav_item)
+        
+        # Create the final navigation structure
+        navigation = {
+            "navigation": [
+                {
+                    "section": "API Reference",
+                    "skip-slug": True,
+                    "contents": nav_contents
+                }
+            ]
+        }
+        
+        return yaml.dump(navigation, default_flow_style=False, sort_keys=False, allow_unicode=True)
+
+    def _build_nav_item_recursive(self, item: ItemData) -> dict[str, t.Any] | None:
+        """Build navigation item recursively following sphinx autodoc2 toctree logic."""
+        full_name = item["full_name"]
+        slug = self._generate_slug(full_name)
+        
+        # Get children (same logic as sphinx toctrees)
+        subpackages = list(self.get_children(item, {"package"}))
+        submodules = list(self.get_children(item, {"module"}))
+        
+        if subpackages or submodules:
+            # This has children - make it a section with skip-slug
+            section_item = {
+                "section": full_name.split(".")[-1],  # Use short name for section
+                "skip-slug": True,
+                "path": f"{slug}.md",
+                "contents": []
+            }
+            
+            # Add subpackages recursively (maxdepth: 3 like sphinx)
+            for child in sorted(subpackages, key=lambda x: x["full_name"]):
+                child_nav = self._build_nav_item_recursive(child)
+                if child_nav:
+                    section_item["contents"].append(child_nav)
+            
+            # Add submodules as pages (maxdepth: 1 like sphinx)
+            for child in sorted(submodules, key=lambda x: x["full_name"]):
+                child_slug = self._generate_slug(child["full_name"])
+                section_item["contents"].append({
+                    "page": child["full_name"].split(".")[-1],  # Use short name
+                    "path": f"{child_slug}.md"
+                })
+            
+            return section_item
+        else:
+            # Leaf item - just a page
+            return {
+                "page": full_name.split(".")[-1],  # Use short name
+                "path": f"{slug}.md"
+            }