[CI/Tests] Keep the API reference generator here

[pallasathena92]

What this PR does

Moves the API reference generator into this repository. hack/genref/ now holds the genref version, config.yaml, the page templates and generate.sh, which builds the page from a checkout of OME.

• The "API reference is current" job and the Move the OME Pin workflow call the script instead of OME's make genref and hack/genref/website.
• The pin workflow generates with the baseline's hack/genref, which is the copy that the pin pull request's own check uses.
• config.yaml and the templates are copied unchanged from OME at the pinned commit, except the header comment in pkg.tpl, which named a Make target. The regenerated page differs only in that comment.
• CONTRIBUTING.md, AGENTS.md and the automation README describe the script.

Why we need it

The config and the templates only describe this site's page, and the site left OME in ome-projects/ome#1192. With them here, a change to the page's layout or to the genref version is one pull request in this repository. The only thing this check then reads from OME is its source at the commit in ome.ref, so OME can remove hack/genref/website.

genref still has to run inside the OME checkout: it resolves OME's types through OME's go.mod, and it loads its templates from the working directory. The script copies the templates into a scratch directory in the checkout and removes it afterwards.

How to test

• The "API reference is current" check on this pull request runs the new script.
• With OME at the pinned commit next to this repository, hack/genref/generate.sh ../ome leaves git status clean. I also ran it against a copy of OME with hack/genref deleted, to confirm that nothing is read from there.
• python3 -m unittest discover -s hack/nightly-docs -p '*_test.py' has one new test, for the pin workflow's step.

After this merges, a pull request in ome-projects/ome removes hack/genref/website. The contributing pages still describe the in-repo workflow; their rewrite is a separate, planned change.

Checklist

• Every commit is signed off (git commit -s)
• pnpm lint && pnpm check && pnpm test && pnpm build passes locally

Summary by CodeRabbit

• New Features

  • Added generated API reference documentation for OME types, including field requirements, status details, version markers, and links to external type documentation.
  • Improved API reference generation checks to report an error when the expected page is missing or empty.

• Documentation

  • Updated contributor guidance and the API reference page to explain how to generate and update the reference.
  • Updated nightly documentation workflow guidance to describe its API reference generation process.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (3)

CONTRIBUTING.md — configured
src/lib/content/contributing/writing-docs.md — configured
README.md — configured

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 776023ad-8a14-4739-9dc3-45838b626d48

📥 Commits

Reviewing files that changed from the base of the PR and between 39670f2 and e6c0bf3.

📒 Files selected for processing (12)

• .github/workflows/move-ome-pin.yml
• .github/workflows/website.yml
• AGENTS.md
• CONTRIBUTING.md
• hack/genref/config.yaml
• hack/genref/generate.sh
• hack/genref/markdown/members.tpl
• hack/genref/markdown/pkg.tpl
• hack/genref/markdown/type.tpl
• hack/nightly-docs/README.md
• hack/nightly-docs/move_pin_test.py
• src/lib/content/reference/api/ome.v1beta1.md

Included review availability: This review used your included allowance. 2 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

---

📝 Walkthrough

Walkthrough

This change adds a repository-owned API reference generator using configuration and Markdown templates, then updates the website and pin-move workflows to invoke it. It also updates generation instructions, workflow tests, and the generated page notice.

Changes

API reference generation

Layer / File(s)	Summary
Reference rendering rules hack/genref/config.yaml, hack/genref/markdown/*	The configuration defines hidden members, excluded types, the OME API package, and external type links. Templates render kinds and supporting types, including fields, markers, validation details, and status types.
Generator execution and workflow integration hack/genref/generate.sh, .github/workflows/website.yml, .github/workflows/move-ome-pin.yml, hack/nightly-docs/move_pin_test.py	The script validates an OME checkout, installs and runs genref, checks for a nonempty page, and copies it to the output directory. The website workflow invokes the script, while the pin-move workflow runs the generator from its baseline archive. A workflow test checks the pin-move invocation.
Generation instructions and page metadata AGENTS.md, CONTRIBUTING.md, hack/nightly-docs/README.md, src/lib/content/reference/api/ome.v1beta1.md	Repository guidance, contribution instructions, pin-move documentation, and the generated page notice describe the script and its inputs.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Website as Website workflow
  participant PinMove as Pin-move workflow
  participant Baseline as Baseline revision
  participant Generator as generate.sh
  participant OME as OME checkout
  participant Genref as genref v0.28.0
  Website->>Generator: Generate API reference
  Generator->>OME: Validate module and read Go version
  Generator->>Genref: Install and run with configuration and templates
  Genref->>OME: Read API types
  Genref-->>Generator: Write generated page
  Generator-->>Website: Copy page to output directory
  PinMove->>Baseline: Read BASE_SHA
  Baseline-->>PinMove: Provide hack/genref archive
  PinMove->>Generator: Run archived script against OME

Loading

Merge Risk: ⚪ Minimal · up to e6c0b

The generator and workflow changes are ready to merge after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (10 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: moving and maintaining the API reference generator in this repository.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (10 skipped: 10 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}