Distributing Documentation to Other Developers

Share your documentation by hosting it on a web server.

Overview

As soon as you create a Swift framework or package, DocC is ready to generate structured documentation for the public types in your code base. Whether you only have documentation comments in your source files, or you craft a full learning experience that includes articles and tutorials, you can easily share the documentation in your code base with other developers.

To share your documentation, you create a documentation archive, a self-contained bundle that has everything you need, including:

  • Compiled documentation from in-source comments, articles, tutorials, and resources

  • A single-page web app that renders the documentation

Distributing your documentation involves the following steps:

  1. Export your documentation using the docc command-line tool.

  2. Share your documentation by hosting it on a website.

Generate a Publishable Archive of Your Documentation

To create a documentation archive for a Swift package, use the SwiftPM DocC Plugin or use Xcode’s Build Documentation command.

Alternatively, use the docc command-line tool directly, for example:

docc convert MyNewPackage.docc \
  --fallback-display-name MyNewPackage \
  --fallback-bundle-identifier com.example.MyNewPackage \
  --fallback-bundle-version 1 \
  --additional-symbol-graph-dir .build \
  --output-dir MyNewPackage.doccarchive

When publishing documentation to an audience that has access to your project’s sources; for example, with an open source project hosted on GitHub, consider configuring DocC to automatically include links to the declarations of your project’s symbols.

For example, in the following screenshot, the “ParsableCommand.swift” link below the declaration navigates to the ParsableCommand declaration in the project’s GitHub repository.

[Image]

To configure DocC to generate links to your project’s sources, use the source service configuration flags like so:

GitHub

docc convert […] \
    --source-service github \
    --source-service-base-url https://github.com/<org>/<repo>/blob/<branch> \
    --checkout-path <absolute path to local checkout>

GitLab

docc convert […] \
    --source-service gitlab \
    --source-service-base-url https://gitlab.com/<org>/<repo>/-/tree/<branch> \
    --checkout-path <absolute path to local checkout>

BitBucket

docc convert […] \
    --source-service bitbucket \
    --source-service-base-url https://bitbucket.org/<org>/<repo>/src/<branch> \
    --checkout-path <absolute path to local checkout>

These arguments can also be provided to swift package generate-documentation if you’re using the SwiftPM DocC Plugin or via the OTHER_DOCC_FLAGS build setting when building in Xcode.

Send a Documentation Archive Directly to Developers

Because a documentation archive is a self-contained bundle, you can easily share it with other developers. For example, you can send it by email just like a regular document, include it with a binary distribution of your framework or package, or make it downloadable from a website.

To remove an imported documentation archive, place your pointer over the item to display the More button, and then choose Remove.

Host a Documentation Archive on Your Website

When DocC exports a documentation archive, it includes a single-page web app in the bundle. This web app renders the documentation content as HTML, letting you host the documentation archive on a web server.

For reference documentation and articles, the web app uses a URL path that begins with /documentation. For tutorials, the URL path begins with /tutorials. For example, if a project contains a protocol with the name MyNewProtocol, the URL to view the MyNewPackage documentation might resemble the following:

https://www.example.com/documentation/MyNewPackage/MyNewProtocol

Host a Documentation Archive with a File Server

You can host documentation archives you create with DocC from the Swift 5.7 toolchain and later using a regular file server. By default, the server hosts the documentation at the root of the website, like the “MyNewPackage” example above. To host the documentation at a specific subpath, pass a custom hosting base path for the --hosting-base-path option when you build the documentation archive.

docc convert MyNewPackage.docc \
  --additional-symbol-graph-dir .build \
  --output-dir MyNewPackage.doccarchive \
  --hosting-base-path MyProject/Base/Path

DocC adds the provided hosting base path before the path of each documentation page. For example, the URL to view for MyNewProtocol protocol in the MyNewPackage documentation might resemble the following:

https://www.example.com/MyProject/Base/Path/documentation/MyNewPackage/MyNewProtocol
                        ╰────────┬────────╯
                       your custom base path

You can also configure the base path path via the --hosting-base-path option when building documentation using the SwiftPM DocC Plugin or via the DOCC_HOSTING_BASE_PATH build setting when building documentation in Xcode.

Host a Documentation Archive Using Custom Routing

A file server is the recommended solution to host your documentation. But, if you need more control over how the server hosts your content, you can configure the request routing of your web server so it responds to documentation requests with the data and assets within the documentation archive.

To host a documentation archive on your website, do the following:

  1. Copy the documentation archive to the directory that your web server uses to serve files. In this example, the documentation archive is MyNewPackage.doccarchive.

  2. Add a rule on the server to rewrite incoming URLs that begin with /documentation or /tutorial to MyNewPackage.doccarchive/index.html.

  3. Add another rule for incoming requests to support bundled resources in the documentation archive, such as CSS files and image assets.

The following example .htaccess file defines rules suitable for use with Apache:

# Enable custom routing.
RewriteEngine On

# Route documentation and tutorial pages.
RewriteRule ^(documentation|tutorials)\/.*$ MyNewPackage.doccarchive/index.html [L]

# Route files and data for the documentation archive.
#
# If the file path doesn't exist in the website's root ...
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# ... route the request to that file path with the documentation archive.
RewriteRule .* MyNewPackage.doccarchive/$0 [L]

With these rules in place, the web server provides access to the contents of the documentation archive.

After configuring your web server to host a documentation archive, keep it up to date by using a continuous integration workflow that builds the documentation archive using docc, and copies the resulting .doccarchive to your web server.