How do I share a Sphinx build without deploying it?

Drag the whole `_build/html` folder into Comma. It uploads `index.html` as the report and the rest of the directory — stylesheets, search index, images and the other HTML pages — as report assets, rewriting relative references so the build works at a URL. No Read the Docs project, no static host, no CI deploy step.

Do links between pages still work?

Yes. Sibling HTML pages in the bundle are uploaded alongside the entry page and their references are rewritten, so ` ` resolves. That is what makes a multi-page docs build shareable rather than just its front page.

Can reviewers comment on a specific paragraph of the docs?

Yes, and this is the reason to publish a build for review at all. A reviewer highlights the sentence that is wrong and pins the correction to it, instead of writing 'the auth section is confusing' in a pull request thread that points at reStructuredText source.

Is this a replacement for hosting docs publicly?

No. Comma is for the review round — preview a build before it ships, share a draft with a customer, get sign-off on the migration guide. Published docs belong on your docs host; the draft that needs three people's opinions belongs somewhere with comments on it.

What are the size limits?

The entry HTML is capped at 5 MB, each asset at 25 MB, with 250 MB and 500 files per report. A typical Sphinx build for a mid-size project fits with room to spare; very large API references may need to be split by subpackage.

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

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 and the API reference.

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

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 →

Share OpenAPI docs — same review problem, API reference flavour
Share an HTML report · Comment on HTML
Publish from CI · Embed a report

Share a Sphinx build

Publish the build

Why review a build instead of the source

Limits

Try it

Related