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.

6 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.

5 Likes
8

Hi @franklin can you share some example project where I could try it ?
I tried to follow the steps in the documentation, but it did not work.
My setup:

  • Link to repo, where I tried to document it with links to source files GitHub - gadireddi226/OSLogStoreExample: Here is Documentation
  • I installed locally the latest docc and docc-renderer
  • I added DOCC_EXEC to project file
  • I added the additional flags (Other DocC Flags): --source-service github --source-service-base-url https://github.com/gadireddi226/OSLogStoreExample/blob/main --checkout-path /path/to/OSLogStoreExample
    I tried it with the latest docc version and latest docc-renderer and I added the additional flags.
    But it still does not seem to generate the link to sources.
9

Hi @gadireddi226, following the steps you outlined on your project, I'm able to see the links to GitHub in the rendered documentation. Are you browsing your documentation in your web browser, or in Xcode? Note that the renderer that's built into Xcode's documentation viewer will support source links in an upcoming release of Xcode.

To view source links right now, you can use the main branch of Swift-DocC Render and publish your documentation to GitHub Pages or preview locally by running a command like python3 -m http.server within your DocC archive and opening http://localhost:8000/documentation/testoslogger in your browser.

If you run into further issues, I'd encourage you to create a GitHub Issue so investigate this further. I'd prefer keeping this forum thread focused on the feature's evolution. Thank you!

1 Like