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