# Share Sphinx Docs — A Whole HTML Build on One Link

Canonical: https://commareports.com/share-sphinx-docs
Published: 2026-08-23

> Sphinx builds a directory of HTML you cannot email. Drop the _build/html folder into Comma: cross-page links keep working, reviewers comment on the paragraph they object to, and there is no docs server to run.

# Share a Sphinx build

`make html` produces a directory. Directories are the least shareable unit in
software: you cannot paste one into Slack, you cannot attach one to a ticket,
and zipping it produces the email that ends with "just clone the repo and
build it yourself" — which nobody does, so the docs ship unreviewed.

The usual fix is to deploy a preview. That works if you already have preview
infrastructure and the reviewer is an engineer. It does not work for the
technical writer, the support lead, or the customer you promised a look at
the migration guide.

## Publish the build

```bash
sphinx-build -b html docs docs/_build/html
```

Then drag `docs/_build/html` onto Comma. The folder upload picks `index.html`
as the entry, uploads the rest of the tree as assets, and rewrites relative
`src` / `href` references so the build renders as itself — theme CSS, search
box, images, and the links from one page to the next.

To do it from CI instead, zip the build and publish the archive the same way
you would any bundle; see [publishing from CI](/docs/ci) and the
[API reference](/docs/api).

## Why review a build instead of the source

reStructuredText review catches typos. Rendered-build review catches the
things that actually cost you support tickets: a code sample that reads fine
in source and wrong on the page, a table that wraps into nonsense, a section
order that made sense to the author and to no one else.

- **Comments anchor to the rendered sentence.** See
  [commenting on HTML](/comment-on-html).
- **Each rebuild is a revision.** PATCH the same report id and reviewers can
  see exactly what changed since their last pass.
- **Access is per report** — private, team, domain-gated, or named reviewers.
  See the [sharing model](/docs/sharing).

## Limits

- **Entry HTML: 5 MB.** Assets: 25 MB per file, 250 MB and 500 files total.
- **Scripts run, sandboxed:** `allow-scripts`, no `allow-same-origin`. Sphinx's
  search box works; anything that needs a same-origin fetch to a server does not.
- **60 requests/minute per token.**

## Try it

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

**[Publish a docs build →](https://commareports.com/)**

### Related

- [Share OpenAPI docs](/share-openapi-docs) — same review problem, API reference flavour
- [Share an HTML report](/share-html-report) · [Comment on HTML](/comment-on-html)
- [Publish from CI](/docs/ci) · [Embed a report](/embed-html-report)