Skip to content
AppDues
Log in
Contact salesSign up

Migrating an iOS SDK's docs from Jazzy to DocC

DocC is Apple's documentation compiler and viewer, and it offers a more structured reading experience than a flat symbol list. This guide walks through a Jazzy-to-DocC migration that keeps releases flowing, uses build warnings to catch stale symbol links, organizes docs into topics, publishes to GitHub Pages and works around DocC's missing version selector. Concrete figures and setup details below come from a published engineering account of one team's own migration, so treat them as a reference point to measure against your project rather than a guarantee.

Why consider DocC over Jazzy

Jazzy is a mature open-source generator and remains a reasonable baseline. DocC adds a reader-facing structure Jazzy does not provide out of the box: a curated landing experience, topic-based grouping and a look that matches Xcode's Quick Help. For an SDK with many public symbols, that structure helps new readers find entry points instead of scanning an alphabetical list.

The strongest operational argument is symbol-link validation. DocC's compiler can emit warnings when a documentation link no longer matches the source code, which turns stale references into visible build output rather than silent drift.

Decision checklist before you start

Use this checklist to decide whether the migration is worth the effort for your SDK:

  • Do you want a guided entry point rather than a flat symbol index? DocC topics and categories support that.
  • Do you need build-time detection of broken symbol references? The RUN_DOCUMENTATION_COMPILER build setting enables it.
  • Do you publish docs from CI on each release? DocC supports static-site export for GitHub Pages.
  • Do you need multiple doc versions selectable from one site? DocC does not provide a version selector; plan a workaround.
  • Do you need Objective-C alongside Swift docs? A language selector is not built in.

If most answers are yes, the migration is likely worthwhile. If you only need a symbol dump and do not publish per release, the cost may outweigh the benefit.

Step 1: Move docstrings to a format both tools accept

The migration does not have to be a flag day. The first step is to rewrite docstrings so that Jazzy and DocC can both parse them. Because Jazzy already follows most of DocC's conventions, the edit is usually mechanical rather than a rewrite. Keeping both generators working means you can ship releases and regenerate docs while the migration is in progress, and you can switch back if a DocC build fails.

A practical way to sequence this: convert one module's docstrings, regenerate with both tools, and compare the rendered output before touching the next module. That keeps the diff reviewable and isolates any formatting regression to a single area.

Step 2: Turn on the documentation compiler to catch broken symbol links

Set the Xcode build setting RUN_DOCUMENTATION_COMPILER to Yes. With that enabled, DocC compiles documentation as part of the normal build and emits a warning whenever a symbol reference in the docs does not resolve. In the published case, that compile step took about 0.2 seconds for their SDK; treat that as a data point from one project, not a guarantee for yours, and measure your own build time before deciding how often to run it.

Treat these warnings as the primary cleanup signal. A warning means a docstring points at a symbol that has been renamed, removed or misspelled; fix the reference rather than suppressing the warning.

Step 3: Organize symbols into topics and categories

Once DocC produces roughly the same output as Jazzy, the real improvement begins. DocC lets you group symbols into topics and categories, so the landing page can present a reading order instead of an undifferentiated list. Group by the reader's task, for example configuration, displaying products and purchase flow, rather than by internal module layout.

This is the step that changes the reader's first impression. A topic page can introduce what the SDK does and then link to the symbols a developer needs next.

Step 4: Publish to GitHub Pages from CI

DocC can export a static site that GitHub Pages can serve. A workable pattern is a CI job that regenerates and deploys the docs on each SDK release so the published site tracks the shipped version. Apple documents the export and publishing flow, including the Swift Package Manager plugin that handles the GitHub Pages layout.

A local preview lane is worth adding before the CI deploy. Previewing the generated site catches formatting problems before a release publishes them.

Step 5: Work around the missing version selector

DocC does not provide a version selector for serving multiple SDK versions from one site. A workaround that has worked in practice has four parts:

  1. Create a folder with one subfolder per SDK version.
  2. Host the docs in a separate repository so doc versions are independent of source branches.
  3. Add a root page that redirects visitors to the latest version.
  4. Update that redirect in CI whenever a new release ships.

This keeps the docs site decoupled from the source repository's branch layout and gives readers a predictable default.

Two different problems: broken links vs. missing versioning

It helps to separate two failure modes that both surface during a DocC migration:

  • Broken symbol links are a documentation accuracy problem. The compiler warns about them, and the fix is to correct the docstring reference. These are detectable and closable.
  • Missing version selection is a product gap in DocC itself. No build warning will appear, and the fix is architectural: separate folders, a separate docs repository and a CI-maintained redirect.

Treating the second as a bug to fix in docstrings wastes time; treating the first as an accepted limitation lets stale references accumulate.

Worked example: using the warning signal

Suppose a public method is renamed from an old signature to a new one. Without validation, the docstring still links to the old name and the published page shows a dead reference. With RUN_DOCUMENTATION_COMPILER set to Yes, the next build emits a warning naming the unresolved symbol. The author updates the docstring to the new signature, rebuilds, and the warning clears. The compile cost per build is the price of that feedback loop, and it is small compared with discovering the break after a release.

What to plan for next

Three improvements are worth tracking after the initial migration:

  • Interactive tutorials for the SDK's main use cases, which DocC supports but which require authoring effort.
  • A native version selector, which DocC does not yet provide.
  • A language selector for viewing Objective-C docs alongside Swift, which is also not built in.

None of these block a migration; they are follow-on work that improves the reader experience once the structural move is complete.

Frequently asked questions

Can I migrate from Jazzy to DocC without pausing releases?

Yes. The approach is to first rewrite docstrings into a format both generators accept, keep Jazzy producing docs while DocC is validated, and only then switch the publishing pipeline. Because Jazzy already follows most of DocC's conventions, the docstring edit is usually small.

What does RUN_DOCUMENTATION_COMPILER actually do?

It is an Xcode build setting. When set to Yes, DocC compiles the documentation during a normal build and emits a warning if a symbol reference in the docs does not match the source code. The published case reports about 0.2 seconds for its SDK; measure your own project rather than assuming that figure.

Does DocC support multiple documentation versions?

Not natively. DocC has no built-in version selector. A common workaround is to publish one subfolder per SDK version from a separate docs repository, with a root redirect page that CI updates to point at the latest release.

How do I publish DocC docs to GitHub Pages?

DocC can export a static site, and Apple documents a publishing flow for GitHub Pages including a Swift Package Manager plugin. A typical setup adds a CI job that regenerates and deploys the docs on each SDK release, plus a local preview step to catch formatting issues before publishing.

Can I show Objective-C docs alongside Swift docs?

Not through a built-in DocC language selector. A language selector is a known gap, so plan a separate mechanism if you need to expose Objective-C reference material next to the Swift docs.