Add navigation tracking and YAML generation to FernRenderer #4
+240
−78
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add navigation tracking to FernRenderer with _navigation_items list - Implement _track_navigation_item method to track rendered packages/modules - Add _generate_slug method to create URL-friendly slugs - Add slug to frontmatter in render_item method for predictable navigation - Implement build_navigation_tree method to create hierarchical structure - Add generate_navigation_yaml method to output Fern-compatible YAML - Modify CLI to support --nav-output flag for navigation YAML generation - Create single FernRenderer instance in CLI to track across all items - Add PyYAML dependency to pyproject.toml - Update test regression files with new expected output - Fix all ruff linting issues and mypy type checking errors Co-Authored-By: [email protected] <[email protected]>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
- Remove slug field from frontmatter (Fern auto-generates from path) - Update navigation YAML to use path instead of slug - Remove _generate_slug method (no longer needed) - Update test regression files to match new format - All tests passing, ruff and mypy clean Co-Authored-By: [email protected] <[email protected]>
- Convert dots and underscores to hyphens in file paths - Matches actual markdown filename format (e.g., nemo-rl-experience.md) - Navigation YAML now correctly references the generated markdown files - Tests passing, ruff and mypy clean Co-Authored-By: [email protected] <[email protected]>
- Updated subpackage links to use full hyphenated path - Simplified submodule links to always use hyphenated format - All cross-page links now match file slugs (e.g., package-a) - Within-page anchors still use underscores for compatibility - Tests updated and passing Co-Authored-By: [email protected] <[email protected]>
- Filenames use Python module names directly (e.g., package.submodule.md) - Navigation paths now match: ./package.submodule.md - Cross-page links use full module names (e.g., package.submodule) - Tests updated and passing, ruff and mypy clean Co-Authored-By: [email protected] <[email protected]>
- Filenames now use hyphens: package-a.md, package-a-c.md - Navigation paths match: ./package-a.md, ./package-a-c.md - Cross-page links use hyphens: package-a - Page names keep original format: package.a (for display) - CLI updated to write hyphenated filenames for Fern renderer - All navigation paths verified to match actual files - Tests passing, ruff and mypy clean Co-Authored-By: [email protected] <[email protected]>
- Filenames now use underscores: package_a.md, package_a_c.md - Navigation paths match: ./package_a.md, ./package_a_c.md - Cross-page links use underscores: package_a, package_a_c - Existing underscores in module names are preserved - CLI updated to convert dots to underscores for Fern renderer - All navigation paths verified to match actual files - Tests passing, ruff and mypy clean Co-Authored-By: [email protected] <[email protected]>
- Section names now use full module path: 'package.a' instead of 'a' - Each section includes its own page as first item in contents - Matches nvidia-nemo pattern where sections have associated pages - Cross-page links verified to work: link 'package_a' -> file 'package_a.md' - Removed unused variable, tests passing, ruff and mypy clean Co-Authored-By: [email protected] <[email protected]>
- Sections now have path field: section + path + contents - Removed redundant page entry for section's own page - Matches Fern's section-with-path pattern - Example: section 'package.a' has path './package_a.md' directly - Tests passing, ruff and mypy clean Co-Authored-By: [email protected] <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add navigation tracking and YAML generation to FernRenderer
Summary
Implements navigation tracking and hierarchical YAML generation for the FernRenderer to enable automatic Fern navigation structure creation from Python package hierarchies.
Key changes:
_navigation_itemsas they're renderedbuild_navigation_tree()creates hierarchical structure,generate_navigation_yaml()exports to Fern-compatible YAML--nav-outputflag to specify where navigation YAML should be writtenlayout: overviewto packages/modules (no slug - Fern auto-generates from path)Navigation format (following nvidia-nemo pattern):
page(full_name) andpath(file path) onlyReview & Testing Checklist for Human
End-to-end test with real Fern site: Generate docs for a Python package with the CLI using
--nav-output, integrate the markdown files and navigation YAML into an actual Fern docs site, and verify:Verify link integrity: Check that internal markdown links (like
[Class](#packageclass)) resolve correctly - navigate between pages and verify anchors work with Fern's auto-generated slugsTest navigation YAML validity: Verify the generated YAML:
./pages/api-reference/prefix)Check edge cases: Test with packages that have:
Notes
pathonly (no slugs)type: ignore[assignment]on line 536 due to mypy tuple unpacking limitation - acceptable but worth noting./pages/api-reference/prefix - may need adjustment for different directory structuresDevin session: https://app.devin.ai/sessions/a4dda89fec3343f1888ff3e2111e9ccd
Requested by: [email protected] (@Ryan-Amirthan)