DocC's own documentation - no explanation of how to create Catalogue

Development Swift-DocC
1

Hi,

I'm working my way through the Documentation for DocC itself.

There appears to be a slight omission: how to actually create a catalogue.

One starts here: Documenting a Swift framework or package where it states:

DocC combines the public API information from the Swift compiler with the contents of the documentation catalog to generate a much richer DocC Archive.

Use a documentation catalog when you want to include any of the following...

But no explanation of how to create a documentation catalogue, nor any description of how one is made-up.

Then as one reads on, there is the page Adding supplemental content to a documentation catalog which reads:

A documentation catalog contains files that enrich your source documentation comments. Two types of files that documentation catalogs can contain are articles and extension files.

and goes on to explains the format of these two types of file, but again, no explanation of how to create a catalogue.

On this page Adding images it states:

Important

Include the image files in your documentation catalog. For more information, see Documenting a Swift Framework or Package.

Which leads back the first page.

Continuing on: this page Adding structure to your documentation pages states:

For projects that don’t include a documentation catalog, DocC generates a basic landing page that provides an entry point to your framework’s symbol documentation. However, by adding a documentation catalog, you can include a custom landing page that provides a rich and engaging experience for adopters of your framework.

But still no instructions of how to add a documentation catalogue.

It's probably an oversight - but at no point is a doc catalogue defined or is it explained how to create one.

How does one create one?

(Bug filed)

2

The simplest version is adding a directory, and a base catalog usually has at least one markdown file within it, the format of which has conventions that DocC looks for to indicate what it maps to. The directory is often named "Documentation.docc" or something similar, but the name is again more convention than rule.

If the markdown file top-level # heading has a symbol marker (meaning the double-backticks around something - akin to ``MyFramework``, and the symbol name matches the name of the library, then it'll be taken as the top-level page that provides the structure for the documentation. There's more convention in there, as it's expected that there'll be a single line underneath that symbol marker with an abstract for the library, followed by an overview (marked off with ## Overview) and so on.

There can also be (and you'll see it in some of Apple's documentation catalogs) an Info.plist with additional metadata about the catalog, but if it's missing, the whole system continues to work and there's command line options that can fill in that information if you want or need it.

The other notable convention is that the location of the catalog is typically expected in the source directory of the library itself (it lines up with the idea of one catalog per module being created). For example, if you're Swift package was for a library called Fred, the default source location would generally be /Sources/Fred and the conventional place for the catalog would be in /Sources/Fred/Documentation.docc.

The swift-docc-plugin leans more on these conventions as defaults, but you pass through CLI options to specify alternative locations or details. One big example of this is the content that makes up TSPL (The Swift Programming Language). If you glance in the repo, you'll note that the catalog is a top-level directory named TSPL.docc with contents within it.

The underlying driver command that does the heavy lifting for DocC (the executable docc that's included in the toolchain) is happy enough to render just the contents of a catalog into it's expected archive structure, which is exactly what's happening for the Swift book.

(And thank you for the bug, I think this is definitely something that should be documented as well)

1 Like
3

Thank-you for such a detailed answer. Shortly after posting I discovered a WWDC video from 2001 which showed how one can create one from within Xcode. Those videos look lovely and are presented and produced well, but are absolutely no substitute for indexable proper textual docs. (Something, something, a picture isn’t always worth a thousand words…)

This also had me stumped until I watched the video. It would be good to mention this in the docs as well. I had no idea that the catalogue had to be in a specific section of the package. The doc catalogues are not compiled in Xcode unless they are in the correct directory.

FYI, Xcode also fails to compile the docs (with an error) if there is more than one doc catalogue in a sources folder. (It appears to pass both paths to the tool, which is not expecting more arguments).

I have filed a Feedback about this against Xcode (FB16682748) as it only appears to affect Xcode.

Thanks again.

2 Likes
4

Ah, I now see where the DocC docs are kept and have submitted a PR

1 Like