DocC landing page for library target within package?

Using Swift
1

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.

Screenshot 2024-04-18 at 15.08.02
Screenshot 2024-04-18 at 15.08.021886×648 100 KB

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.

2

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

Share and Enjoy

Quinn “The Eskimo!” @ DTS @ Apple

3

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
4

Did you figure this out @JetForMe? I am having the same problem and can't figure out whether I need the docc file to match my framework name, or if it's in the wrong place.

If you have figured it out, could you post an example of what your file structure looks like please?

5

The name of the markdown file doesn't matter, only the contents of the file matters. All markdown files should be inside your .docc catalog directory. For the top level framework page, it must begin with the following title:

# ``YourFrameworkName``

For example, in @JetForMe's case:

# ``Raise3DAPI``

Note the required double-backticks.

2 Likes