How to build DocC documentation using a Command Line and distribute it to Developers

We can build the DocC documentation and distribute it manually using Xcode. But as with any manual work, it can be automated. Imagine if you have a CI job that builds documentation automatically, on every merge to the main branch, and shares the new version with other developers. This is where the Command Line comes in handy.

Building a DocC archive

In order to build a DocC documentation, open the Command Line and navigate to the folder with your project:

cd path/to/your/project

Then build the documentation archive:

xcodebuild docbuild \
-scheme SCHEME_NAME \
-destination 'name=iPhone 13 Pro Max' \
-derivedDataPath OUTPUT_PATH 

We use the xcodebuild docbuild tool to build the documentation with some required parameters. The first one is scheme which is a scheme name of our project. Then we have destination that specifies the platform which is used for the build.

The get a list of all destinations supported by our project we can run the following command:

xcodebuild -list -scheme SCHEME_NAME

The last parameter is derivedDataPath which specifies the path where the generated archive will be saved.

If everything goes well the xcodebuild tool should generate documentation files in the OUTPUT_PATH folder.

Finding the DocC archive

When we build a DocC documentation Xcode generates many files and finding an Archive file can be difficult. To make our life easier we can use the find command:

find OUTPUT_PATH -type d -name '*.doccarchive'

This command searches the OUTPUT_PATH for the files that have the .doccarchive extension. If it finds any file it will return the path to that file, e.g.: ~/tmp/docs/MyProject.doccarchive.

Distributing the DocC Documentation

Once we get the documentation archive, we can share it with other developers. The simplest way to do this is just to copy the archive file and send it via email or any communicator. We can also generate a static website and host the documentation on a server.

Generating a website from DocC archive from Command Line

In order to generate a website we have to execute following command:

$(xcrun --find docc) process-archive \
transform-for-static-hosting PATH_TO_ARCHIVE_FILE \
--output-path PATH_TO_WWW_OUTPUT

This command runs the docc tool that transforms the archive into a website.

It requires a PATH_TO_ARCHIVE_FILE which specifies a path to the archive and output path PATH_TO_WWW_OUTPUT where  the website files will be generated in.

Once the website is generated, we can copy all the files onto the server and host the documentation from there.

When we host a DocC documentation as a website, by default, the root / path serves an empty page. The actual documentation is available under the /documentation/PROJECT_NAME slug. So, if we host loacally, to acess the documentation, instad of http://localhost/ we have to request the http://localhost/documentation/MyProject

If we want to host the documentation on GitHub or GitLab pages we have to slightly modify the docc command:

$(xcrun --find docc) process-archive \
transform-for-static-hosting PATH_TO_ARCHIVE_FILE \
--output-path PATH_TO_WWW_OUTPUT
--hosting-base-path NAME_OF_THE_GITHUB_REPOSITORY

Here we added the hosting-base-path parameter, which specifies the name of the GitHub or GitLab repository. For example, if my project is available under https://github.com/mtynior/MyProject, then we would pass the MyProject as the value of the hosting-base-path parameter.

That's all we need to build and distribute the DocC documentation. More information are available in Official Apple Documentation, under Distributing Documentation to External Developers.