Fix README badges, add AI-readable documentation for veralang.dev#327
Conversation
- Reorder badges: CI → Codecov → CodeRabbit (logical grouping) - Fix pronunciation: (v-EER-a) → (v-ERR-a) - Add CI workflow status badge next to version on veralang.dev Co-Authored-By: Claude <noreply@anthropic.invalid>
|
Important Review skippedReview was skipped due to path filters ⛔ Files ignored due to path filters (1)
CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughAdds site-generation and verification tooling plus CI/pre-commit integration, updates documentation/readme and an allowlist line number; generates and checks AI-readable assets under Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Dev as Developer
participant Pre as Pre-commit
participant CI as CI Lint Job
participant Build as Build Script\n(scripts/build_site.py)
participant Check as Check Script\n(scripts/check_site_assets.py)
participant Docs as Docs Directory
Dev->>Pre: Commit site-related files
Pre->>Build: run build_site.py
Build-->>Docs: write llms.txt, llms-full.txt, robots.txt, sitemap.xml, index.md
Dev->>CI: Push / open PR
CI->>Check: run check_site_assets.py
Check->>Build: import build helpers to generate expected content
Check->>Docs: compare regenerated files to committed files (sitemap: existence only)
Check-->>CI: exit 0 if match else exit 1
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested labels
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment Tip You can disable the changed files summary in the walkthrough.Disable the |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #327 +/- ##
=======================================
Coverage 95.88% 95.88%
=======================================
Files 45 45
Lines 15150 15150
=======================================
Hits 14526 14526
Misses 624 624 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Generate llms.txt (curated doc index), llms-full.txt (complete docs), robots.txt, sitemap.xml, and index.md via build_site.py. Add JSON-LD structured data to landing page, .well-known/ai-plugin.json manifest, and .nojekyll for GitHub Pages dotfile serving. Pre-commit hook regenerates on source changes; CI verifies freshness via check_site_assets.py. Update README project structure, TESTING.md hook count, and CONTRIBUTING.md accordingly. Co-Authored-By: Claude <noreply@anthropic.invalid>
There was a problem hiding this comment.
Actionable comments posted: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
CONTRIBUTING.md (1)
74-88:⚠️ Potential issue | 🟡 MinorAdd explicit site-asset doc-validation guidance in this section.
The section now says 21 hooks, but it still omits the site-asset docs workflow (
build_site.py/check_site_assets.py) and the expectation not to skip doc-validation after README/docs edits.Proposed doc update
After running `pre-commit install`, every commit is automatically checked by 21 hooks including: @@ - README, SKILL.md, HTML, and spec code blocks parse correctly +- Site assets are regenerated/validated for docs-related changes (`build_site.py` / `check_site_assets.py`) - Documentation counts match live codebase - License compliance (all dependencies MIT-compatible) - Browser parity (JS runtime matches Python runtime) + +When editing README/docs content, do not bypass `pre-commit` or the relevant `scripts/check_*` validations.As per coding guidelines: "Pre-commit/CI enforcement expectation: documentation changes must pass the doc-validation hooks ... plus site asset regeneration/validation. Don’t bypass running
pre-commitor the relevantscripts/check_*validations after README/docs edits."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CONTRIBUTING.md` around lines 74 - 88, The CONTRIBUTING.md pre-commit hooks list omits the site-asset documentation validation workflow; update the section that lists "21 hooks" to explicitly mention the site asset/doc validation step and the scripts involved (build_site.py and scripts/check_site_assets.py or check_site_assets.py), and add a short guidance sentence that contributors must run pre-commit or the site asset validation scripts (and not skip doc-validation) after README/docs edits; reference the exact script names (build_site.py, check_site_assets.py) and the README/docs change expectation so readers know which tools to invoke.
🤖 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 163-174: The file reads for SKILL.md, AGENTS.md, and FAQ.md use
Path.read_text() without an explicit encoding; update each call (the expressions
ROOT / "SKILL.md").read_text(), (ROOT / "AGENTS.md").read_text(), and (ROOT /
"FAQ.md").read_text() to pass encoding="utf-8" so files are read consistently
across platforms (preserve the existing SKILL.md YAML-stripping logic using
re.sub on skill).
- Around line 350-352: The loop that writes files (iterating over files, using
DOCS and calling path.write_text(content)) doesn't ensure the target directory
exists, causing FileNotFoundError; before writing each file (or once before the
loop) ensure the directory exists by creating the parent directory (use
DOCS.mkdir(parents=True, exist_ok=True) or path.parent.mkdir(parents=True,
exist_ok=True)) so path.write_text(content) can succeed without errors.
In `@scripts/check_site_assets.py`:
- Around line 24-32: Unused import build_sitemap_xml is present in the import
tuple; remove build_sitemap_xml from the from-import list (the import that
currently brings in DOCS, build_index_md, build_llms_full_txt, build_llms_txt,
build_robots_txt, build_sitemap_xml, _version) so the module no longer imports
an unused symbol and the script remains consistent with skipping sitemap.xml
content comparison.
- Around line 48-51: The checker uses path.read_text() which defaults to locale
encoding and can cause false mismatches; update the comparison to call
path.read_text(encoding="utf-8") and likewise update any write_text() and
read_text() usages in build_site.py to use encoding="utf-8" so generated files
are written and read deterministically; ensure the logic around stale.append(f"
{name}: missing...") and the content comparison still uses the same UTF-8
decoded string for equality checks.
In `@TESTING.md`:
- Line 370: Update the "Validation Scripts" section to match the lint table:
include check_site_assets.py in the earlier scripts inventory (the section that
lists the "Eleven scripts") and adjust the count/description accordingly so the
list and the lint table (which already shows check_site_assets.py) are
consistent; ensure the filenames check_conformance.py, check_examples.py,
check_version_sync.py, check_spec_examples.py, check_readme_examples.py,
check_skill_examples.py, check_faq_examples.py, check_html_examples.py,
check_site_assets.py, and check_licenses.py appear in the inventory in the same
order/format as the lint table.
---
Outside diff comments:
In `@CONTRIBUTING.md`:
- Around line 74-88: The CONTRIBUTING.md pre-commit hooks list omits the
site-asset documentation validation workflow; update the section that lists "21
hooks" to explicitly mention the site asset/doc validation step and the scripts
involved (build_site.py and scripts/check_site_assets.py or
check_site_assets.py), and add a short guidance sentence that contributors must
run pre-commit or the site asset validation scripts (and not skip
doc-validation) after README/docs edits; reference the exact script names
(build_site.py, check_site_assets.py) and the README/docs change expectation so
readers know which tools to invoke.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: d8064ac2-ec2c-4a58-91df-b2f2175b0a17
⛔ Files ignored due to path filters (8)
docs/.nojekyllis excluded by!docs/**docs/.well-known/ai-plugin.jsonis excluded by!docs/**docs/index.htmlis excluded by!docs/**docs/index.mdis excluded by!docs/**docs/llms-full.txtis excluded by!docs/**docs/llms.txtis excluded by!docs/**docs/robots.txtis excluded by!docs/**docs/sitemap.xmlis excluded by!docs/**
📒 Files selected for processing (10)
.github/workflows/ci.yml.pre-commit-config.yamlCLAUDE.mdCONTRIBUTING.mdREADME.mdTESTING.mdscripts/build_site.pyscripts/check_readme_examples.pyscripts/check_site_assets.pytests/test_readme.py
…sync - Add explicit encoding="utf-8" to all read_text()/write_text() calls in build_site.py and check_site_assets.py for cross-platform safety - Add DOCS.mkdir(parents=True, exist_ok=True) before writing files - Remove unused build_sitemap_xml import from check_site_assets.py - Update TESTING.md: "Eleven scripts" → "Twelve scripts", add check_site_assets.py row to validation scripts table - Update CONTRIBUTING.md: mention site-assets hook and regeneration workflow for documentation source changes Co-Authored-By: Claude <noreply@anthropic.invalid>
Co-Authored-By: Claude <noreply@anthropic.invalid>
Summary
scripts/build_site.pyauto-generates site assets from source docs;scripts/check_site_assets.pyverifies freshness in CI; pre-commit hook regenerates on source changesNew files
docs/llms.txtdocs/llms-full.txtdocs/robots.txtdocs/sitemap.xmldocs/index.mddocs/.well-known/ai-plugin.jsondocs/.nojekyllscripts/build_site.pyscripts/check_site_assets.pyTest plan
python scripts/check_site_assets.pyconfirms freshnesspython scripts/check_doc_counts.pycounts consistentpython scripts/check_readme_examples.pypassespython scripts/check_html_examples.pypasses🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
New Features
Chores
Tests