Skip to content

Fix README badges, add AI-readable documentation for veralang.dev#327

Merged
aallan merged 4 commits into
mainfrom
fix/readme-tweaks
Mar 21, 2026
Merged

Fix README badges, add AI-readable documentation for veralang.dev#327
aallan merged 4 commits into
mainfrom
fix/readme-tweaks

Conversation

@aallan

@aallan aallan commented Mar 20, 2026

Copy link
Copy Markdown
Owner

Summary

  • Badge reorder: CI → Codecov → CodeRabbit (logical grouping)
  • Pronunciation fix: (v-EER-a) → (v-ERR-a)
  • CI badge on website: Added next to "Current Version" on veralang.dev landing page
  • AI discoverability: Added llms.txt, llms-full.txt, robots.txt, sitemap.xml, index.md, JSON-LD structured data, .well-known/ai-plugin.json, and .nojekyll to make veralang.dev accessible to AI agents per the llmstxt.org standard
  • Build pipeline: scripts/build_site.py auto-generates site assets from source docs; scripts/check_site_assets.py verifies freshness in CI; pre-commit hook regenerates on source changes
  • README Project Structure: Updated to include new docs/ directory entries

New files

File Purpose
docs/llms.txt Curated AI-readable documentation index
docs/llms-full.txt Complete documentation compiled for LLMs (~24K tokens)
docs/robots.txt Crawler directives with sitemap reference
docs/sitemap.xml XML sitemap for search engines
docs/index.md Markdown companion of landing page
docs/.well-known/ai-plugin.json OpenAI plugin manifest
docs/.nojekyll Disable Jekyll so dotfiles are served
scripts/build_site.py Generator script for all generated docs
scripts/check_site_assets.py CI freshness checker

Test plan

  • All 21 pre-commit hooks pass
  • python scripts/check_site_assets.py confirms freshness
  • python scripts/check_doc_counts.py counts consistent
  • python scripts/check_readme_examples.py passes
  • python scripts/check_html_examples.py passes
  • CI passes on GitHub
  • Verify llms.txt accessible at veralang.dev/llms.txt after merge

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation

    • Updated pronunciation guide and reordered README badges; added generated site assets and an OpenAI plugin manifest to published docs.
  • New Features

    • Added tooling to generate AI-readable site assets and a companion validation tool to check they are up to date.
  • Chores

    • Pre-commit and CI inventories updated to run the new site-generation and validation steps.
  • Tests

    • Adjusted README allowlist mapping used by tests to reflect relocated content.

- 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>
@coderabbitai

coderabbitai Bot commented Mar 20, 2026

Copy link
Copy Markdown

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)
  • docs/.well-known/ai-plugin.json is excluded by !docs/**

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4e9d42a2-d401-4468-a8b6-ee8afe00266b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds 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 docs/ and ensures they are built/validated in CI and pre-commit.

Changes

Cohort / File(s) Summary
Docs / README
README.md
Reordered badges (moved CodeRabbit Pull Request Reviews shield below Codecov), adjusted Vera pronunciation (v-EER-a)(v-ERR-a), and added vera/docs/ entries plus generated site files listing.
CI workflow
.github/workflows/ci.yml
Added a lint job step to run python scripts/check_site_assets.py (inserted between existing README/example checks and license checks).
Pre-commit config
.pre-commit-config.yaml
Added local site-assets hook running .venv/bin/python scripts/build_site.py (system language, no filenames) and scoped to specific site-related files.
Docs guidance
CLAUDE.md, CONTRIBUTING.md, TESTING.md
Documented new site build/check steps, updated pre-commit hook count (20 → 21) and validation script count (11 → 12) where applicable.
Site build script
scripts/build_site.py
New executable that parses vera/__init__.py for __version__ and generates docs/llms.txt, docs/llms-full.txt, docs/robots.txt, docs/sitemap.xml, and docs/index.md; prints per-file stats and exits 0.
Site check script
scripts/check_site_assets.py
New CLI that regenerates expected assets via build_site helpers, compares them to committed docs/ files (sitemap only existence-checked), and exits 1 on any missing/mismatched assets.
README example allowlist
scripts/check_readme_examples.py, tests/test_readme.py
Updated allowlist mapping for the “Project Roadmap” code block from line 623633 in both the script and test.

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
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

docs, ci, tests

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title directly addresses both primary objectives: README badge reordering and the addition of AI-readable documentation assets for veralang.dev.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/readme-tweaks

Comment @coderabbitai help to get the list of available commands and usage tips.

Tip

You can disable the changed files summary in the walkthrough.

Disable the reviews.changed_files_summary setting to disable the changed files summary in the walkthrough.

@codecov

codecov Bot commented Mar 20, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.88%. Comparing base (21102c8) to head (20b94cf).
⚠️ Report is 5 commits behind head on main.

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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>
@aallan aallan changed the title Fix README badge order, pronunciation, and add CI badge to website Fix README badges, add AI-readable documentation for veralang.dev Mar 20, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 | 🟡 Minor

Add 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-commit or the relevant scripts/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

📥 Commits

Reviewing files that changed from the base of the PR and between fe77463 and 787ccb3.

⛔ Files ignored due to path filters (8)
  • docs/.nojekyll is excluded by !docs/**
  • docs/.well-known/ai-plugin.json is excluded by !docs/**
  • docs/index.html is excluded by !docs/**
  • docs/index.md is excluded by !docs/**
  • docs/llms-full.txt is excluded by !docs/**
  • docs/llms.txt is excluded by !docs/**
  • docs/robots.txt is excluded by !docs/**
  • docs/sitemap.xml is excluded by !docs/**
📒 Files selected for processing (10)
  • .github/workflows/ci.yml
  • .pre-commit-config.yaml
  • CLAUDE.md
  • CONTRIBUTING.md
  • README.md
  • TESTING.md
  • scripts/build_site.py
  • scripts/check_readme_examples.py
  • scripts/check_site_assets.py
  • tests/test_readme.py

Comment thread scripts/build_site.py
Comment thread scripts/build_site.py Outdated
Comment thread scripts/check_site_assets.py
Comment thread scripts/check_site_assets.py
Comment thread TESTING.md
aallan and others added 2 commits March 21, 2026 19:48
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant