Trying out the `--source-service` option for generating documentation

I'm trying to generate links to github sources based on the feature that was added to link to GitHub, BitBucket, and Gitlab. It is generating updated json files, but it's not displaying links back to sources. I suspect I'm missing something, and wanted to check - see if anything is obviously wrong in how I'm doing this, or if I'm missing something else. I haven't tried this feature previously - just got excited to see if I could make it work.

I have a shell script in the root of the repo cloned from git (parallel to Package.swift) that runs swift package .... I'm generating content into a local ./docs directory, and then hosting the package through GitHub Pages off a specific branch. I've added the following options to the swift package generate-documentation command:

    --source-service github \
    --source-service-base-url https://github.com/ordo-one/package-benchmark/blob/main \
    --checkout-path .

(the whole command if you want to see it in my repo)

(After reading the details in docc's distributing-documentation-to-other-developers.md, I wasn't super-positive I had checkout-path correct, but I think it's intended to be a local path, relative to where I'm running the command, to where I've cloned the repo, is that correct?)

I'm working on a fork of the original repo, but I used the original repo as the detail for source-service-base-url.

The end result renders without issue, but I'm not seeing any references back to GitHub. That said, I'm also not entirely sure what I should be looking for - so I may just be missing the obvious. The hosted result is at https://heckj.github.io/package-benchmark/documentation/benchmark/benchmark/(Documentation)

I did noticed that the updated command generated new/additional JSON files, and a few new symbols, for example:

/docs/data/documentation/benchmark/benchmark/executablepath.json
/docs/data/documentation/benchmark/benchmark/target.json
/docs/documentation/benchmark/benchmark/executablepath/index.html
/docs/documentation/benchmark/benchmark/target/index.html

Does the markdown need to be amended with references to these symbols to make the links appear? - such as ``Benchmark/Benchmark/target``?

Any advice, or details on how to debug what's appearing (or not appearing, as the case may be?)

This was all done with swift 5.8 toolchain that was included in the latest Xcode beta, if that makes a difference.

swift-driver version: 1.75.1 Apple Swift version 5.8 (swiftlang-5.8.0.117.11 clang-1403.0.22.8.60)
Target: arm64-apple-macosx13.0

I suspect the issue here is that the --checkout-path is provided is a relative path rather than an absolute direct path to the checkout. Or rather, DocC should accept a relative path. If that's indeed the issue, this is probably where things would fail: swift-docc/SourceRepository.swift at main · apple/swift-docc · GitHub. We'd want to make DocC resolve the relative path to an absolute path before determining the path of the source file relative to the root of the checkout.

1 Like

Got it, I'll try try handing in an absolute path to the CLI through my script for now - and if that works, I'll open an issue to file an improvement to allow relative paths.

1 Like

@Franklin Oh - and thank you for taking the time to look at this and provide a bit of guidance. I really appreciate it!

1 Like

Absolute path definitely made a difference. I spotted this in the JSON files:

diff --git a/docs/data/documentation/benchmark/blackhole(_:).json b/docs/data/documentation/benchmark/blackhole(_:).json
index e7034a9..0793940 100644
--- a/docs/data/documentation/benchmark/blackhole(_:).json
+++ b/docs/data/documentation/benchmark/blackhole(_:).json
@@ -50,6 +50,10 @@
         "name" : "Benchmark"
       }
     ],
+    "remoteSource" : {
+      "fileName" : "Blackhole.swift",
+      "url" : "https:\/\/github.com\/ordo-one\/package-benchmark\/blob\/main\/Sources\/Benchmark\/Blackhole.swift#L21"
+    },
     "role" : "symbol",
     "roleHeading" : "Function",
     "symbolKind" : "func",

And the symbols are now showing up with references to source in the hosted content. Thank you!

1 Like