# Share Scaladoc — API Docs at a URL, No Hosting Step

Canonical: https://commareports.com/share-scaladoc
Published: 2026-09-14

> sbt doc writes an API site into target/. Publish the folder to Comma for one link per version: search intact, private by default, with comments on the signature that needs explaining.

# 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

```bash
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:

```bash
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](https://commareports.com/):

- `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

```bash
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](/docs/api) and
[publishing from CI](/docs/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](/comment-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 →](https://commareports.com/)**

### Related

- [Share Javadoc](/share-javadoc) · [Share Dokka docs](/share-dokka-docs)
- [Share ExDoc output](/share-exdoc) · [Share rustdoc](/share-rustdoc)
- [Share a Maven site report](/share-maven-site-report) · [Share an HTML folder](/share-html-folder)