Building documentation from the command line/global SwiftPM plugin?

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.

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:

The gist are these steps:

  1. build your swift code with symbol extraction and grab those .json files into a specific area
  2. 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
  3. use docc convert to merge those symbol sets with the .docc catalog folder

-- joe

swift package dump-symbol-graph
(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.)

1 Like

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

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.