feat: website narrative restructuring and AI discoverability#408
Conversation
docs/index.html: - Add three link discovery tags for llms.txt, llms-full.txt, and index.md (closes #397) - Add "documentation" field to ComputerLanguage JSON-LD schema entry, pointing to veralang.dev/llms.txt (closes #399) - Merge LLM Integration section into "What Vera Looks Like" with five-example narrative arc: safe_divide, fizzbuzz, classify_sentiment, safe_classify, research_topic — building from pure functions through to Http+Inference - Promote "For Agents" from h3 subsection to standalone h2 section (partial progress on #400) scripts/build_site.py: - Replace hardcoded example/conformance counts with dynamic filesystem reads (_count_examples(), _count_conformance()) so counts stay accurate - Add Inference to the algebraic effects list in llms.txt overview - Add EXAMPLES.md, DESIGN.md, HISTORY.md, KNOWN_ISSUES.md to llms.txt - Update Chapter 9 description to include maps, sets, decimals, JSON, HTML - Add LLM Inference as a key feature in index.md with dedicated bullet Regenerate: docs/llms.txt, docs/index.md, docs/sitemap.xml Co-Authored-By: Claude <noreply@anthropic.invalid>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds cached helper counters for example and conformance files to the site build script, and uses those counts to update generated docs (llms.txt, llms-full.txt, index.md) while rewriting feature/capability text and navigation links. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #408 +/- ##
=======================================
Coverage 90.30% 90.30%
=======================================
Files 49 49
Lines 19100 19100
Branches 220 220
=======================================
Hits 17248 17248
Misses 1848 1848
Partials 4 4
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@scripts/build_site.py`:
- Around line 59-60: The call to _count_examples() is duplicated (once in main()
and again inside build_index_md()), causing redundant filesystem scans; modify
the code to compute example/conformance counts once in main() (using
_count_examples() and _count_conformance()) and pass those values as parameters
into build_index_md(count_examples, count_conformance) (or implement a simple
module-level cache in _count_examples() that returns a stored value on
subsequent calls), then update build_index_md() to consume the passed counts (or
read from the cache) so the filesystem is scanned only once.
- Around line 40-60: check_doc_counts.py currently validates counts in
TESTING.md but not the generated site artifacts, so stale counts can be
committed; extend the validation to parse and verify docs/llms.txt and
docs/index.md (or add a CI step that runs build_llms_txt and diffs generated
files) by reusing the same dynamic counting logic (_count_examples,
_count_conformance) used in build_llms_txt and adding checks that the numbers in
docs/llms.txt and docs/index.md match the computed values; update
check_doc_counts.py to locate and read those files, extract the documented
counts, and fail the check on mismatch (alternatively add a pipeline job to run
build_llms_txt and compare outputs to the checked-in docs).
- Around line 45-51: The _count_conformance() function reads the
tests/conformance/manifest.json using (ROOT / "tests" / "conformance" /
"manifest.json").read_text() without specifying encoding; update that
read_text() call in _count_conformance to include encoding="utf-8" to match
other reads in this file (so _count_conformance uses the same UTF-8 explicit
read as the rest of the script).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: aa34f398-dca8-43b9-bda4-396804ad5e6b
⛔ Files ignored due to path filters (4)
docs/index.htmlis excluded by!docs/**docs/index.mdis excluded by!docs/**docs/llms.txtis excluded by!docs/**docs/sitemap.xmlis excluded by!docs/**
📒 Files selected for processing (1)
scripts/build_site.py
- Add @lru_cache(maxsize=None) to _count_examples() and _count_conformance() so repeated calls within the same build invocation hit the cache rather than rescanning the filesystem (addresses CodeRabbit review comment) - Add encoding='utf-8' to manifest.json read_text() call in _count_conformance() to match all other read_text() calls in this file Note: check_doc_counts.py count validation of docs/ files not added -- check_site_assets.py already does a byte-for-byte diff of the generated files against fresh build output, which is a stricter guarantee. Co-Authored-By: Claude <noreply@anthropic.invalid>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@scripts/build_site.py`:
- Around line 41-47: Replace the use of functools.lru_cache(maxsize=None) with
functools.cache for the _count_examples function: update the decorator on the
_count_examples definition to use `@cache` and ensure functools.cache is imported
(replace or add the import of cache alongside or instead of lru_cache) so the
function uses the simpler built-in cache decorator.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: b32ed7a8-a878-44e4-998b-97a5bbb5de1d
📒 Files selected for processing (1)
scripts/build_site.py
The version string 'v0.0.101' was duplicated in the status section of docs/index.html, creating another place to update on every release. Dropping the version prefix while keeping the description text. Co-Authored-By: Claude <noreply@anthropic.invalid>
functools.cache is the idiomatic alias for lru_cache(maxsize=None) available since Python 3.9. The project requires 3.11+, so this is a straightforward simplification. Applied to both count functions. Co-Authored-By: Claude <noreply@anthropic.invalid>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@scripts/build_site.py`:
- Around line 136-149: build_llms_full_txt currently compiles only SKILL.md,
AGENTS.md, FAQ.md, error codes and grammar but the site now links additional
docs (README, EXAMPLES, DESIGN, CHANGELOG, ROADMAP, HISTORY, vera/README,
TESTING.md, KNOWN_ISSUES.md), so update scripts/build_site.py's
build_llms_full_txt to include those newly linked documents in its source list
(use the same RAW path expansion used elsewhere), concatenate them into
llms-full.txt in the intended order, and ensure the “complete documentation”
claim matches the actual contents if you prefer not to include a file; also
apply the same inclusion or claim-narrowing to the other related
functions/blocks referenced in the review (the other build paths noted in the
comment).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: dc1ff738-6fe2-4ad7-8c83-5d426d1676a2
⛔ Files ignored due to path filters (1)
docs/index.htmlis excluded by!docs/**
📒 Files selected for processing (1)
scripts/build_site.py
The header and docstring claimed 'complete Vera documentation' but the file only contains SKILL.md, AGENTS.md, FAQ, error codes, and grammar — not the 13 spec chapters, README, EXAMPLES.md, DESIGN.md, or the other docs linked from llms.txt. Narrow the claim to 'core language documentation' and point readers to llms.txt for the full index. Adding spec chapters to llms-full.txt (251 KB, ~13 files) is a deliberate architectural decision that warrants its own PR. Co-Authored-By: Claude <noreply@anthropic.invalid>
Summary
docs/index.html - AI discoverability and narrative improvements:
<link>discovery tags to docs/index.html for AI agents #397)scripts/build_site.py - dynamic counts and updated content:
Test plan
Generated with Claude Code
Summary by CodeRabbit