Adding links to source files in Swift-DocC

Development Swift-DocC
,
#1

Hi everyone, I'm happy to propose a new functionality to link symbol documentation pages back to their source code. This is a feature a lot of you had requested, here's the link to the original post by @johannesweiss. The goal of this feature is to make it easier for developers to quickly locate the lines where a symbol is declared in.

The source file link will be placed under the declaration code snippet.

This is an opt-in feature that you use via the following two new flags:

swift package generate-documentation \
  --source-service github \ // GitHub, GitLab, or BitBucket
  --source-service-base-url https://github.com/<org>/<repo>/blob/main

Documentation pages for symbols automatically gain a link to the declaration in source:

Swift (see demo)

swift
swift1872×916 50.8 KB

Objective-C

objc
objc2014×852 37.2 KB

Thank you @dhristov and @Franklin for implementing a prototype. Here are a few links for you to take a closer look:

Swift-DocC PR
Swift-DocC-Render PR
Prototype

I look forward to hearing your thoughts on this proposal!

24 Likes
#2

This looks great thank you! This is definitely a great feature for getting more details on APIs you are working on.

1 Like
#3

Why is the --source-service github argument required?
Could the URL argument be a template string?

For example, if the latest release is 1.1.3, and the unreleased version is 1.1.4:

swift package generate-documentation \
  --source-service-permalink \
  'https://github.com/apple/swift-argument-parser/blob/1.1.4/$FILE#L$LINE'

(There might be better alternatives for the $FILE and $LINE placeholders.)

#4

I think there's a lot of value in hardcoding URL formats for popular hosting services like GitHub, so that users can use this functionality without needing to know how GitHub formats its URLs. The placeholder approach you propose is more flexible though as a future enhancement, e.g., to support source services other than the ones this feature supports natively.

5 Likes
#5

That's awesome, thank you so much! @lukasa / @georgebarnett et al: Does this now fully unblock SwiftNIO's docs in DocC? I think it does, right?

#6

Yes, we're unblocked on this. Our main limiting factor right now is team bandwidth, as we'd like to extract the documentation from the swift-nio repo to avoid it continuing to bloat the repo clone time as the current docs do.

3 Likes
#7

This functionality has now landed in recent Trunk toolchains. I'm adding documentation on how to use it in Add documentation for links to source declarations by franklinsch · Pull Request #360 · apple/swift-docc · GitHub.

4 Likes