How do I share Scaladoc without publishing the library?

Run `sbt doc`, then drop the generated `target/scala-3.x/api/` folder into Comma. `index.html` becomes the report body, the per-package pages and search index upload with it, and you get one URL.

Does Scaladoc's search work at the published URL?

Yes. Scala 3's scaladoc ships a static search index next to the pages, and Comma renders report HTML with scripts enabled inside a sandboxed iframe, so the search box and the sidebar tree keep working.

Where does sbt put the output?

`target/scala-3.3.x/api` for Scala 3, `target/scala-2.13/api` for Scala 2. In a multi-project build each subproject writes its own, under that subproject's `target/`.

Can I publish docs for an internal library privately?

Yes. Access is set per report — private, your team, anyone signed in at your domain, or anyone with the link. That is the case Maven Central and javadoc.io cannot serve.

Can I keep the same link across versions?

Save the report id and PATCH it from the release job. Each publish appends a revision at the same URL, and the revision history shows how the public API moved between versions.

Share Scaladoc

sbt doc is a command nobody runs on purpose. It runs as part of publish, writes an API site into target/, and that site is uploaded to a repository or it is discarded. There is no middle option — which is unfortunate, because the middle is where most Scala code lives: internal libraries, a shared core module, a client's platform.

So the API documentation for the module everybody depends on exists as a directory under target/ that gets deleted by the next sbt clean.

Build it

sbt doc
# Scala 3 → target/scala-3.3.1/api/
# Scala 2 → target/scala-2.13/api/

For a multi-project build, the one people want is usually a specific module:

sbt core/doc

api/
├── index.html
├── com/acme/core/        # one page per package, class, trait, object
├── scripts/              # search index + navigation
└── styles/  images/

Opened from the filesystem the pages render, but search does not — the index is fetched over XHR, which a browser blocks from a file:// origin. That is the usual reason a zipped copy of API docs feels broken when it arrives by email.

Drop the folder in

Drag the api/ directory (or a zip of it) into Comma:

index.html becomes the report body.
Every package and class page plus scripts/ and styles/ upload alongside it, with relative references rewritten to the uploaded copies — which is what makes search and the member filter work again.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin).

No artifactory path, no static bucket, no Pages branch.

From the release job

sbt core/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 target/scala-3.3.1/api/index.html \
        --arg t "core — $VERSION" '{title: $t, html: $html}')"

Supporting pages go up through POST /api/v1/reports/$REPORT_ID/assets as base64. See the API reference and publishing from CI.

The case for commenting on a signature

Scala signatures are where the design is. A comment on def traverse[F[_]: Applicative, A, B](...) — "the implicit here means callers in the http module can't use this" — is a real design objection, and it is nearly impossible to raise usefully in a channel. Anchored to the rendered member page, it stays with the member across doc rebuilds. See commenting on HTML.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A wide API surface can exceed 500 pages — publish one module per report, which is also how people read it.
Scripts run, sandboxed — no same-origin access.
60 requests/minute per token.

Try it

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

Publish Scaladoc →