Building documentation from the command line/global SwiftPM plugin?

JetForMe · August 26, 2023, 4:00am

As far as I can tell, the only way to build DocC docs from source is to include a dependency in in Package.swift on this SwiftPM plugin.

This strikes me as suboptimal, because it depends on the package maintainer to add it. It seems to me that DocC is much like SwiftC, and I should just be able to invoke swift docc or something like that. But so far I haven't found a way to do that. When using Xcode, I am able to just build the documentation, without Package.swift supporting it.

One way to solve that would be to be able to add SwiftPM plugins globally to my system, external to the Package. Is there a way to do that? Again, my googling has failed to turn up a way to do so.

UPDATE: The docs say " Alternatively, use the docc command-line tool directly," but it’s not clear to me how to install that command line tool, other than to build it from sources and install it on my system. Really feels like something that should be installed with the Xcode command line tools.

Joseph_Heck · August 26, 2023, 5:21pm

the docc plugin is hugely more convenient, but definitely not required. Before it existed (and still) you could extract the symbols for your code, and use that with a documentation catalog directory to build up the docs. It's not documented because, frankly, its not recommended. But it's definitely possible. I made a script for a number of projects called docbuild that handled all the various steps, and you're welcome to pillage from it to do what you're after. One of those copies:

github.com

swiftviz/Scale/blob/main/docbuild.bash

#!/bin/bash

echo "Make sure you've rebased over the current HEAD branch:"
echo "git rebase -i origin/main docs"

set -e  # exit on a non-zero return code from a command
#set -x  # print a trace of commands as they execute

# borrowed filepath from
# https://github.com/apple/swift-markdown/blob/main/bin/update-gh-pages-documentation-site

filepath() {
    [[ $1 = /* ]] && echo "$1" || echo "$PWD/${1#./}"
}

ROOT_DIR="$(dirname $(filepath $0))"
#echo "filepath is $(filepath $0)"
#echo "ROOT_DIR is ${ROOT_DIR}"
#
#rm -rf .build

This file has been truncated. show original

The gist are these steps:

build your swift code with symbol extraction and grab those .json files into a specific area
get rid of any symbol sets for modules OTHER than the one you're documenting - important bit here, leaving in extra stuff can cause trouble/bugs/crashes
use docc convert to merge those symbol sets with the .docc catalog folder

-- joe

SDGGiesbrecht · August 27, 2023, 2:39pm

swift package dump-symbol-graph
then
(xcrun) docc convert

Both halves are documented and are more versatile than the plug‐in. Use either’s --help to find out about customization options. (@Joseph_Heck’s script demonstrates the second half well, but appears unaware of the supported way to do the first.)

Joseph_Heck · August 27, 2023, 4:13pm

Thanks @SDGGiesbrecht - I'd seen the dump command, but never used it.

JetForMe · August 28, 2023, 1:49am

Wow, that really is a pain! it seems like a real shortcoming of the documentation compiler and or swift. So many steps to generate docs. But the plugin is cumbersome because you can't just download some package and generate docs, if they haven't added the plugin to their Package.swift.

I'm running into this right now trying to build docs for my Vapor project in Xcode 15b7; I was hoping to use the command line tools to further explore the issues I'm running into, but the projects don't have the plugin dependency.

MinerMinerMain · January 19, 2025, 8:34pm

Go and open the toolchain and search for the bin directory, then it should contain a file called docc. Link to the file and bring the link to a more accessible place, then run at that location docc to get started