docs: DocC API docs #338
docs: DocC API docs #338
Conversation
| @@ -60,7 +60,7 @@ let package = Package( | |||
| .package(url: "https://github.com/ReactiveCocoa/ReactiveSwift.git", from: "7.1.1"), | |||
| .package(url: "https://github.com/ReactiveX/RxSwift.git", from: "6.6.0"), | |||
| .package(url: "https://github.com/swiftlang/swift-syntax", "509.0.0" ..< "601.0.0-prerelease"), | |||
| .package(url: "https://github.com/pointfreeco/swift-case-paths", from: "1.1.0"), | |||
| .package(url: "https://github.com/pointfreeco/swift-case-paths", from: "1.5.5"), | |||
There was a problem hiding this comment.
Bumped to fix an issue with compiling under Xcode 16.3.
There was a problem hiding this comment.
the new docs look amazing – nice work! left some minor thoughts, and one final question: i assume the existing docs lint check is not going to pass this go-around since the script was removed in this PR, but subsequently the check will no longer occur – does that sound right?
| run: Scripts/generate_docs.sh | ||
|
|
||
| - name: Deploy to GitHub Pages | ||
| uses: crazy-max/ghaction-github-pages@df5cc2bfa78282ded844b354faee141f06b41865 |
There was a problem hiding this comment.
is this the crazy-max we need or deserve? j/k, but how did you pick this flavor of page deployment? TCA repo uses this one, which 'wins' the GH star popularity contest (i don't know enough to know if they are comparable/equivalent though).
There was a problem hiding this comment.
This file is copied from swift-modals, which is in turn based on Blueprint's. We've been using this action to publish Blueprint's jazzy docs for about 5 years. I couldn't tell you what the playing field looked like back then, but I know it's been reliable.
There was a problem hiding this comment.
When I was setting up swift-modals CI jobs I got some security warnings that suggested using SHAs instead of tags, so that's why they're versioned that way.
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
| - uses: jdx/mise-action@5083fe46898c414b2475087cc79da59e7da859e8 | ||
| - uses: maxim-lobanov/setup-xcode@60606e260d2fc5762a71e64e74b2174e8ea3c8bd |
There was a problem hiding this comment.
is this the only place we use this? what does it do differently than how we set things up in the swift workflow?
There was a problem hiding this comment.
Effectively the same thing AFAIK, just a little more configuration-based style of definition than running sudo xcode-select inline.
|
|
||
| env: | ||
| # Xcode 16.3 gets us Swift 6.1, required for docc merge | ||
| XCODE_VERSION: 16.3 |
There was a problem hiding this comment.
tangential thought – i wonder if we could do doc generation without Xcode in a reasonably-straightforward way now that 'swiftly' is a thing.
edit: or perhaps i'm wildly mistaken and docc is an Xcode toolchain rather than Swift toolchain thing?
There was a problem hiding this comment.
You can, and I started out that way, but it's not really better since Xcode 16.3 is preinstalled while swiftly has to download it on every run. fwiw I also found it annoying to have swiftly installed locally and uninstalled it.
If you want to try it on something, I saved the snippet:
# Get Swift 6.1 for docc merge
- name: Install Swiftly and Swift 6.1
run: |
curl -O "https://download.swift.org/swiftly/darwin/swiftly.pkg"
installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
# the swiftly binary is extracted to ~/local/bin/swiftly on macOS
~/.swiftly/bin/swiftly init --verbose --assume-yes --skip-install
. ~/.swiftly/env.sh
hash -r
swiftly install 6.1.0 --use
hash -r
which docc
Vapor also has a swiftly github action but it only supports linux.
There was a problem hiding this comment.
Also, you still need to use xcodebuild docbuild to build the documentation since it imports UIKit. Swiftly will only get you a docc that's independent from xccrun docc for manipulating the docc archives.
Right. I will need to disable the requirement first in order to merge this PR, and then it'll be gone. |
Adds DocC generated API docs, published here, and removes the old doc generation pipeline.
Checklist