Publish Swift SymbolKit's documentation to GitHub pages

[Kyle-Ye]

Summary

This sets the foundation for deploying Swift SymbolKit's documentation to GitHub pages.

• Adds the Swift-DocC Plugin as a dependency of Swift-SymbolKit.
• Adds a script to simplify deployment of documentation to GitHub pages.
• Adds check-source and test script and fix missing headers.
• Update README docs (Remove some duplication and add a link to the github page).
• Adds pull request template file as other swift-docc related repo.

After merging this PR, we should be able to prepare a gh-pages branch on the main swift-docc-symbolkit repo with no content on it, run the bin/update-gh-pages-documentation-site script and have docs available.

Dependencies

None.

Testing

With Swift 5.6, run:

swift package --disable-sandbox preview-documentation --target SymbolKit

and confirm the Swift-DocC preview works as expected.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

Most of the content of this PR comes from @ethan-kusters. This is just a port for swift-docc-symbolkit repo.
See more info here swiftlang/swift-markdown#32

[Kyle-Ye]

@swift-ci please test

[ethan-kusters]

This looks great! Thanks so much for putting this together @Kyle-Ye.

I went ahead and used the script you included to deploy to my fork and it looks like everything is working as expected: https://ethan-kusters.github.io/swift-docc-symbolkit/documentation/symbolkit/.

[Kyle-Ye]

@swift-ci please test

[Kyle-Ye]

By the way, swift-docc-plugin has a dependency on main branch of swift-docc-symbolkit. Would it consider to be a circle reference?

[Kyle-Ye]

@swift-ci please test

[ethan-kusters]

By the way, swift-docc-plugin has a dependency on main branch of swift-docc-symbolkit. Would it consider to be a circle reference?

That is a great question... Let me check.

[Kyle-Ye]

@swift-ci please test macOS

[Kyle-Ye]

The macOS Platform CI just exits directly🤔. Could you help confirm with it? @ethan-kusters

[ethan-kusters]

@swift-ci please test

[ethan-kusters]

By the way, swift-docc-plugin has a dependency on main branch of swift-docc-symbolkit. Would it consider to be a circle reference?

That is a great question... Let me check.

It looks like it does:

% swift build
Fetching https://github.com/apple/swift-docc-plugin from cache
Fetched https://github.com/apple/swift-docc-plugin (0.42s)
Creating working copy for https://github.com/apple/swift-docc-plugin
Working copy of https://github.com/apple/swift-docc-plugin resolved at main
error: cyclic dependency declaration found: SymbolKit -> SwiftDocCPlugin -> SymbolKit

Hm. I think we'll need to figure out a workaround here... It might be we just need to add a custom script for building documentation instead of using the plugin. I'm intentionally trying to keep the number of dependencies the plugin has a to a minimum for this exact reason but SymbolKit is unavoidable at the moment.

[ethan-kusters]

Unfortunately I don't think we can land this as-is since it will introduce a cyclic dependency with the Swift-DocC Plugin.

[Kyle-Ye]

Unfortunately I don't think we can land this as-is since it will introduce a cyclic dependency with the Swift-DocC Plugin.

Got it, seems like the dependency was introduced 3 days ago by swiftlang/swift-docc-plugin#7.

So there is 2 ways to solve this:

1. Remove SymbolKit dependency on Swift-Docc Plugin. (I think "Swift-Docc Plugin" is a basic plugin and should not depends on "SymbolKit")
2. Change the PR to use a new script instead of using Swift-Docc Plugin which causes a duplication and potential inconsistency.

Personally I prefer way 1, but way 2 is acceptable for me. Can I get your suggestion on this? @ethan-kusters cc @bitjammer

[ethan-kusters]

Unfortunately I don't think we can land this as-is since it will introduce a cyclic dependency with the Swift-DocC Plugin.

Got it, seems like the dependency was introduced 3 days ago by apple/swift-docc-plugin#7.

So there is 2 ways to solve this:

1. Remove SymbolKit dependency on Swift-Docc Plugin. (I think "Swift-Docc Plugin" is a basic plugin and should not depends on "SymbolKit")
2. Change the PR to use a new script instead of using Swift-Docc Plugin which causes a duplication and potential inconsistency.

Personally I prefer way 1, but way 2 is acceptable for me. Can I get your suggestion on this? @ethan-kusters cc @bitjammer

@bitjammer can speak to this more but my understanding is in the longer-term we'd like to move the new snippet-build executable to a separate repository so it can be used by more projects than just the swift-docc-plugin but, for now, the plugin is the place where it makes the most sense.

So I think we should plan on using a custom script instead of the Swift-DocC Plugin for now but plan on removing it and adopting the Plugin as soon as it becomes possible.

I've written a couple of similar scripts before, so I'm happy to open a PR against your branch later today to add the basis for something and we can iterate on it there.

[bitjammer]

So unfortunately, moving the tool to a new repo will not solve the dependency problem as SwiftPM plugins share their dependency graph with their clients. This is not an intentional limitation and ought to be fixed but I don't see it happening very soon. We can't remove the dependency on SymbolKit because we use the Symbol Graph model to communicate snippet information to DocC. I'm seeing what my options are for deploying the tool elsewhere but if we can have this one exception in the meantime, I would appreciate it!

[ethan-kusters]

@Kyle-Ye I've opened a PR against your branch here with a script as a temporary workaround until we resolve these issues with the plugin:

• Temporarily remove Swift-DocC Plugin Kyle-Ye/swift-docc-symbolkit#1

Feel free to merge it directly into this PR if it looks good to you.

[Kyle-Ye]

@swift-ci please test

[ethan-kusters]

Looks great! Thanks for all your work on this @Kyle-Ye.

[Kyle-Ye]

The doc page is currently unavailable https://apple.github.io/swift-docc-symbolkit/documentation/symbolkit/

Seems that we need to create/enable the some environment like the following.

cc @franklinsch

[franklinsch]

It's live now: https://apple.github.io/swift-docc-symbolkit/documentation/symbolkit. Thanks for the amazing work here once again @Kyle-Ye 🚀