DocC landing page for library target within package?

I’m trying to make a landing page for the library target of my two-target Swift package (the other is a command line executable). Unfortunately, the DocC documentation isn’t precise about where to place files (it only says to create a file and name it “to match the name of the framework”). Moreover, the directories corresponding to my targets don’t match the target names, which I don’t believe they should have to, but maybe DocC is getting tripped up by that. The framework name is Raise3DPI, the directory name is API.

If I put the landing page inside the documentation catalog, when I generate the docs in Xcode, I get two top-level entries for my library. One is the landing page as an extension of the documentation generated from the source code. The other is generated for the documentation catalog in the target.

If I put it under API/, it gets ignored.

My source tree looks like this:

.
├── Package.resolved
├── Package.swift
└── Sources
    ├── API
    │   ├── Documentation.docc
    │   │   ├── EnablingPrinterAPI.md
    │   │   ├── Raise3DAPI.md
    │   │   └── Resources
    │   └── Raise3DAPI.swift
    └── CLI
        └── Raise3DCLI.swift

Package.swift:

// swift-tools-version: 5.10

import PackageDescription

let package = Package(
	name: "Raise3D",
	platforms: [.macOS(.v13)],
	products:
	[
		.library(name: "Raise3DAPI", targets: ["Raise3DAPI"]),
		.executable(name: "raise3d", targets: ["CLI"])
	],
	dependencies:
	[
		.package(url: "https://github.com/apple/swift-argument-parser",		from: "1.0.0"),
		.package(url: "https://github.com/apple/swift-docc-plugin",			from: "1.0.0"),
	],
	targets:
	[
		.target(name: "Raise3DAPI", path: "Sources/API"),
		.executableTarget(
			name: "CLI",
			dependencies:
			[
				.product(name: "ArgumentParser", 		package: "swift-argument-parser"),
				.target(name: "Raise3DAPI"),
			]),
	]
)

Can anyone tell me where to put the markdown file that should be the top level of my individual targets’ documentation? I want to do something similar for the CLI.

I usually follow the path laid down by the sample code. Did you try that?

Share and Enjoy

Quinn “The Eskimo!” @ DTS @ Apple

I'll try that. I didn't realize there was an actual sample code project. I'm looking at pages like this one and not seeing a link to the sample, just examples in-line that are imo insufficient.

1 Like