How do I share YARD-generated documentation?

Run `yard doc`, which writes `doc/`, then drag the whole folder into Comma. `doc/index.html` becomes the report body and the class pages, `js/`, `css/` and the search index upload alongside it with references rewritten.

Why does `yard server` exist if the output is static?

Because the generated site's search and frame navigation load sibling files, and browsers restrict those loads from `file://` origins. `yard server` is a workaround for opening it locally; publishing solves it for everyone at once.

Can I publish docs for a gem before releasing it?

Yes — reports are private by default. Share it with named reviewers or your team while the gem is unreleased and open it up when you publish.

How do I keep one URL per gem?

PATCH the same report id from your release workflow. The URL stays stable across versions and each release appends a revision, so the diff between two versions' docs is visible.

Can someone comment on a specific method's docs?

Yes. Anchored threads sit on the rendered method, so "this raises `ArgumentError` too and it isn't documented" lands on the method instead of in an issue.

Share YARD docs

yard doc gives Ruby projects a genuinely good API reference: a class list, a method index, the source of every method one click away, and full-text search. It also gives you yard server, which exists mostly because the generated site does not behave when opened as a file:// path — the frame navigation and search load sibling files that the browser blocks at that origin.

So the docs work on your machine, with a server running, and nowhere else.

Generate

gem install yard
yard doc          # → doc/

Include the private API too if the audience is your own team:

yard doc --no-private --protected

Publish the folder

Drag doc/ (or a zip of it) into the app:

index.html becomes the report body.
The class and method pages, js/, css/, _index.html and the search data upload as assets, and their relative references are rewritten to the uploaded copies — which is precisely the step file:// refuses to do.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so search and the source toggles work.

One URL. No yard server on somebody's laptop, no doc/ committed to git.

From a release workflow

yard doc

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html doc/index.html \
        --arg title "API docs — v$VERSION" '{title: $title, html: $html}')"

PATCH one report id per gem: a stable link for the README, a revision per release. See the API docs for uploading the rest of the folder.

What review adds

Anchored threads on a method — undocumented raises, stale examples, arguments whose meaning changed. See commenting on HTML.
Access per report — private for an unreleased gem, opened up on release. See the sharing model.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A large gem's per-method pages are the thing that approaches the file cap.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish generated docs →