Add llms.txt generation, docs version updater, and CHANGELOG integration#24
Merged
Conversation
Contributor
|
📚 Docs Preview: https://pr-24.tstring-structured-data.pages.dev |
WalkthroughThis PR introduces automated documentation workflows and script-based generators. It extends GitHub Actions to synchronize changelogs and generate llms.txt documentation files from zensical.toml navigation structures, adds Python scripts for version pinning updates in docs, and creates AI-friendly documentation outputs. Changes
Sequence DiagramsequenceDiagram
participant GHA as GitHub Actions
participant Script as build_llms_txt.py
participant TOML as zensical.toml
participant Docs as docs/*.md
participant FS as File System
participant Git as Git Repo
GHA->>Script: Trigger (on docs/TOML/script change)
Script->>TOML: Parse site config & nav
TOML-->>Script: site_name, description, nav tree
Script->>Docs: Extract metadata per page
Docs-->>Script: title, description, content
Script->>FS: Generate llms.txt (summary)
Script->>FS: Generate llms-full.txt (full content)
FS-->>Script: Write confirmation
Script->>Git: Commit & push updates
Git-->>GHA: Workflow complete
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
scripts/build_llms_txt.py (1)
173-186: Optional-section grouping is not recursion-safe for deeper nav trees.Line 173-Line 186 only evaluate one nesting level, so nested optional descendants can be classified/rendered incorrectly when nav depth grows.
Suggested refactor
+ def section_all_optional(section: NavSection) -> bool: + if section.path: + return is_optional(section.path) + return bool(section.children) and all(section_all_optional(c) for c in section.children) + + def iter_leaf_pages(section: NavSection) -> list[PageInfo]: + if section.path: + p = page_map.get(section.path) + return [p] if p else [] + out: list[PageInfo] = [] + for c in section.children: + out.extend(iter_leaf_pages(c)) + return out + main, optional = [], [] for s in sections: - is_opt = (s.path and is_optional(s.path)) or (s.children and all(is_optional(c.path) for c in s.children)) + is_opt = section_all_optional(s) (optional if is_opt else main).append(s) @@ - lines.extend( - fmt(p) - for s in optional - for item in ([s] if s.path else s.children) - if item.path and (p := page_map.get(item.path)) - ) + for s in optional: + for p in iter_leaf_pages(s): + lines.append(fmt(p)) lines.append("")🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scripts/build_llms_txt.py` around lines 173 - 186, The current grouping logic using is_opt = (s.path and is_optional(s.path)) or (s.children and all(is_optional(c.path) for c in s.children)) is only one-level deep and misclassifies deeper optional descendants; replace it with a recursion-safe approach: add a helper (e.g., has_optional_descendant(node) or classify_nav(node)) that walks s.children recursively to determine whether any descendant path is optional (using is_optional) and to collect nodes into main or optional lists; update the loop that builds main/optional to call that helper for each top-level s and update the optional rendering block to iterate recursively (similar to render(s)) using page_map.get to find pages (symbols: is_opt/is_optional, s.children, main, optional, render, fmt, page_map) so nested optional items are correctly grouped and rendered.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/llms-txt.yaml:
- Around line 16-48: The workflow currently uses the pull_request_target trigger
and secrets.PAT while checking out PR code (see pull_request_target,
jobs.update-llms-txt, and uses: actions/checkout@v4), and the condition includes
github.actor == 'koxudaxi' which bypasses the safe-to-fix gating; change the
trigger to pull_request (restricting to non-fork PRs by checking that
pull_request.head.repo.full_name == github.repository or similar), remove the
pull_request_target branch/logic entirely, replace secrets.PAT with github.token
in the checkout step token field, and remove the github.actor == 'koxudaxi'
clause from the if condition so only labeled safe-to-fix PRs (and controlled
push events) can run the job.
---
Nitpick comments:
In `@scripts/build_llms_txt.py`:
- Around line 173-186: The current grouping logic using is_opt = (s.path and
is_optional(s.path)) or (s.children and all(is_optional(c.path) for c in
s.children)) is only one-level deep and misclassifies deeper optional
descendants; replace it with a recursion-safe approach: add a helper (e.g.,
has_optional_descendant(node) or classify_nav(node)) that walks s.children
recursively to determine whether any descendant path is optional (using
is_optional) and to collect nodes into main or optional lists; update the loop
that builds main/optional to call that helper for each top-level s and update
the optional rendering block to iterate recursively (similar to render(s)) using
page_map.get to find pages (symbols: is_opt/is_optional, s.children, main,
optional, render, fmt, page_map) so nested optional items are correctly grouped
and rendered.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 51b2452e-ba8b-4811-954e-8ea44b69a5af
📒 Files selected for processing (9)
.github/workflows/docs.yaml.github/workflows/llms-txt.yaml.gitignoreCHANGELOG.mddocs/llms-full.txtdocs/llms.txtscripts/build_llms_txt.pyscripts/generate_changelog.shscripts/update_docs_version.py
github-actions
Bot
added
the
breaking-change-analyzed
Contributor
Breaking Change AnalysisResult: No breaking changes detected Reasoning: PR #24 only adds documentation tooling (llms.txt generation, docs version updater, changelog improvements) and CI workflow enhancements. No changes were made to library source code, public APIs, parsing behavior, output serialization, or runtime requirements. All changed files are in .github/workflows/, scripts/, docs/, CHANGELOG.md, and .gitignore - none of which affect the library's public interface or behavior. This analysis was performed by Claude Code Action |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary by CodeRabbit
New Features
Chores