Add DocC to SwiftSyntax

[kimdv]

I've been looking into moving the documentation gh-pages, so we can use DocC.

An example can be found here: https://kimdv.github.io/swift-syntax/documentation/swiftsyntax/

I've also been considering to adding Swift Package Index documentaion.

Let me hear what you think. 👍

[ahoppen]

I like the idea of publishing the documentation as GitHub pages. There are a few organizational questions that need to be answered first, like:

• I don’t think we provide GitHub pages for any other repo in the apple organization, so we need to figure out if there are any implications if we start doing so for SwiftSyntax.
• This adds a dependency from SwiftSyntax on swift-docc-plugin which makes it more difficult if that plugin wanted to start using SwiftSyntax in the future because that would create a dependency cycle
• We would need to ensure that the documentation is up-to-date, either by creating a CI job or by requiring every commit to re-generate the docs, similar to what we do with the gyb-generated files

I think all of this is doable but requires some coordination. I’m looking into it but it might take a while.

[kimdv]

I like the idea of publishing the documentation as GitHub pages. There are a few organizational questions that need to be answered first, like:

• I don’t think we provide GitHub pages for any other repo in the apple organization, so we need to figure out if there are any implications if we start doing so for SwiftSyntax.

Swift-NIO does: https://github.com/apple/swift-nio
https://apple.github.io/swift-nio/docs/current/NIOCore/index.html . They use right now jazzy.

• This adds a dependency from SwiftSyntax on swift-docc-plugin which makes it more difficult if that plugin wanted to start using SwiftSyntax in the future because that would create a dependency cycle

It will yes. And the plugin depends on swift-docc, so we need to think carefully here.
Or we can make a branch, what we rebase on main, and generate from that, so it's not part of the official release.
That branch is only used for docs generation.

• We would need to ensure that the documentation is up-to-date, either by creating a CI job or by requiring every commit to re-generate the docs, similar to what we do with the gyb-generated files

Yes. Docc don't support versions either right now, but there is an issue open on swift-docc, so it's tracked.

I think all of this is doable but requires some coordination. I’m looking into it but it might take a while.

[kimdv]

One thing that just hit, was that we must improve the generated docs.
See if we can add missing descriptions python nodes etc.

What it is, what it is used for etc. maybe some inline examples

[ahoppen]

Some improvement suggestions for the landing pages.

[kimdv]

@swift-ci please test

[ahoppen]

@swift-ci Please test

[ahoppen]

I think the commit in this PR has the wrong commit message ;-)

[kimdv]

I think the commit in this PR has the wrong commit message ;-)

Whoops 🤦‍♂️

Changed

[kimdv]

@swift-ci Please test

[kimdv]

Looks like something timed out

Fetching https://github.com/apple/swift-docc-plugin
warning: skipping cache due to an error: Failed to clone repository https://github.com/apple/swift-docc-plugin:
    Cloning into bare repository '/home/build-user/.cache/org.swift.swiftpm/repositories/swift-docc-plugin-a84d795b'...
    fatal: unable to access 'https://github.com/apple/swift-docc-plugin/': Failed to connect to github.com port 443: Connection timed out
Fetching https://github.com/apple/swift-docc-plugin
warning: skipping cache due to an error: Failed to clone repository https://github.com/apple/swift-docc-plugin:
    Cloning into bare repository '/home/build-user/.cache/org.swift.swiftpm/repositories/swift-docc-plugin-a84d795b'...
    fatal: unable to access 'https://github.com/apple/swift-docc-plugin/': Failed to connect to github.com port 443: Connection timed out
Fetching https://github.com/apple/swift-docc-plugin
warning: skipping cache due to an error: Failed to clone repository https://github.com/apple/swift-docc-plugin:
    Cloning into bare repository '/home/build-user/.cache/org.swift.swiftpm/repositories/swift-docc-plugin-a84d795b'...
    fatal: unable to access 'https://github.com/apple/swift-docc-plugin/': Failed to connect to github.com port 443: Connection timed out
error: Failed to clone repository https://github.com/apple/swift-docc-plugin:
    Cloning into bare repository '/home/build-user/build/buildbot_incremental/unified-swiftpm-build-linux-x86_64/repositories/swift-docc-plugin-a84d795b'...
    fatal: unable to access 'https://github.com/apple/swift-docc-plugin/': Failed to connect to github.com port 443: Connection timed out

@swift-ci please test linux

[kimdv]

@swift-ci please test linux

[kimdv]

Failed again so rebased on main and tried again 🤷‍♂️

** Done Generating gyb Files **
** Running code generation **
/home/build-user/build/buildbot_incremental/toolchain-linux-x86_64/usr/bin/swift run --package-path /home/build-user/swift-syntax --enable-test-discovery --configuration release --build-path /home/build-user/build/buildbot_incremental/unified-swiftpm-build-linux-x86_64 --multiroot-data-file /home/build-user/swift/utils/build_swift/resources/SwiftPM-Unified-Build.xcworkspace SwiftSyntaxBuilderGeneration /tmp/tmpxw0zvdn5 --verbose
FAIL: Source generation using SwiftSyntaxBuilder failed
Executing: /home/build-user/build/buildbot_incremental/toolchain-linux-x86_64/usr/bin/swift run --package-path /home/build-user/swift-syntax --enable-test-discovery --configuration release --build-path /home/build-user/build/buildbot_incremental/unified-swiftpm-build-linux-x86_64 --multiroot-data-file /home/build-user/swift/utils/build_swift/resources/SwiftPM-Unified-Build.xcworkspace SwiftSyntaxBuilderGeneration /tmp/tmpxw0zvdn5 --verbose
None
ERROR: command terminated with a non-zero exit status 1, aborting

[ahoppen]

I think the issue is that CI is not allowed to access the internet during the CI run. We might need to disable docc if the SWIFT_BUILD_SCRIPT_ENVIRONMENT environment variable is present, similar to https://github.com/apple/swift-syntax/blob/3e5751ec9b3f829aa380ab2db9169150f93b1ce6/Package.swift#L9

[kimdv]

Something line this @ahoppen ?

[ahoppen]

Yes, that’s what I had in mind.

[kimdv]

@swift-ci please test