Standalone docc compile

thibault-ml · October 14, 2021, 11:34pm

Hello team!

Excited to see DocC being open source!

I was looking to see whether I could create a standalone docc that could be compiled on its own.
What I'm thinking about is a standalone codestyle document.

I tried the following, but it does not seem to work:

> xcrun docc preview Codestyle.docc --fallback-display-name Codestyle --fallback-bundle-identifier com.crowdstrike.codestyle --fallback-bundle-version 1.0.0
[...]
========================================
Starting Local Preview Server
	 Address: http://localhost:8000/
========================================

However, when I go to that address, I greeted by

The page you’re looking for can’t be found.

What am I doing wrong?

The docc was created by Xcode and all it currently contains is the main .md:

# ``Codestyle``

## Overview

Lorem Ipsum

## Topics

### Group

Hello world

It could be worth documenting the process of manipulating standalone docc files, not attached to a Swift Package particularly. For example, I see documentation can have an Info.plist file, but I wasn't able to find any documentation on the format it should have.

Thanks a lot in advance!

franklin · October 15, 2021, 4:43pm

Hi Thibault!

Thanks for bringing this up. Swift-DocC does indeed support building standalone documentation catalogs without an associated Swift module. There is an example of this in the swift-docc repo. You bring up a very relevant point about documenting this use case; you can find documentation for building documentation for Swift frameworks in DocC’s documentation (see Build and Read Documentation for Swift-DocC) but it would be great to have docs for building standalone docs as well. Would you like to create a ticket on bugs.swift.org, or even open a PR? Thank you!