Add DocC to the project and host it where I can read it.
Richard-Gist opened this issue · comments
Is your feature request related to a problem? Please describe.
I like the jazzy docs but I would get so much more from DocC with the articles and nicer layout. Also having those documents available to me locally would be helpful with getting on-boarded.
Describe the solution you'd like
A DocC created for the project or for each framework (whatever makes sense), and a website I can view that DocC.
Describe alternatives you've considered
Keep using Jazzy and the wiki. And then I'll just keep being sad.
Sounds like a great addition - Feel free to open a PR for review when you want some review!
This is a thing: https://github.com/DoccZz/docc2html
Marking this as low priority since our Jazzy docs just got a really nice upgrade
@MattFreiburgAsynchrony and I started to delve into this, but aren't yet sure a good tutorial to try this out on. We were starting down the path of trying to make an app that uses the features of SwiftCurrent, but were concerned that we'd be showing mostly how to make a bespoke app and not necessarily showing the features of the lib. Taking a step back to see if providing a use cases directory a la this to see if that might make more sense.
We like the idea of short nuggets that show you what you can do without prescribing an app that does all the things.
All this is to say that we're working on providing something that can instruct new users of how to consume the lib, but not quite sure what the best medium is.
^ The project I mentioned takes the approach of having a bunch of use cases in one app. That is not necessarily what I had in mind. What I had in mind was more like a bunch of snippets or perhaps very small apps. Matt might have a different idea, but this is what I was thinking.
I messed around a fair bit with trying to get a docc-generating GitHub action set up, leaning on the work from the PointFree guys' at Swift Parsing. I got as far as this:
# Build and deploy DocC to GitHub pages. Based off of @karwa's work here:
# https://github.com/karwa/swift-url/blob/main/.github/workflows/docs.yml
name: Documentation
on:
release:
types:
- published
push:
branches:
- main
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout Package
uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Download Swift 5.5.1
run: wget -q https://download.swift.org/swift-5.5.1-release/ubuntu2004/swift-5.5.1-RELEASE/swift-5.5.1-RELEASE-ubuntu20.04.tar.gz
- name: Extract Swift 5.5.1
run: tar xzf swift-5.5.1-RELEASE-ubuntu20.04.tar.gz
- name: Add Swift toolchain to PATH
run: |
echo "$GITHUB_WORKSPACE/swift-5.5.1-RELEASE-ubuntu20.04/usr/bin" >> $GITHUB_PATH
- name: Checkout swift-docc
uses: actions/checkout@v2
with:
repository: apple/swift-docc
ref: main
path: swift-docc
- name: Cache DocC
id: cache-docc
uses: actions/cache@v2
with:
key: swift-url-docc-build
path: swift-docc/.build
- name: Build swift-docc
if: ${{ !steps.cache-docc.outputs.cache-hit }}
run: |
cd swift-docc; swift build --product docc -c release; cd ..
- name: Checkout swift-docc-render
uses: actions/checkout@v2
with:
repository: apple/swift-docc-render
ref: main
path: swift-docc-render
- name: Build swift-docc-render
run: |
cd swift-docc-render; npm install && npm run build; cd ..
- name: Checkout gh-pages Branch
uses: actions/checkout@v2
with:
ref: gh-pages
path: docs-out
- name: Build documentation
run: >
rm -rf docs-out/.git;
rm -rf docs-out/main;
for tag in $(echo "main");
do
echo "⏳ Generating documentation for "$tag" release.";
if [ -d "docs-out/$tag" ]
then
echo "✅ Documentation for "$tag" already exists.";
else
git checkout "$tag";
mkdir -p Sources/SwiftCurrent/Documentation.docc;
export DOCC_HTML_DIR="$(pwd)/swift-docc-render/dist";
rm -rf .build/symbol-graphs;
mkdir -p .build/symbol-graphs;
mkdir -p x86_64-apple-ios15.2-simulator;
swift build \
--target SwiftCurrent \
-Xswiftc -emit-symbol-graph \
-Xswiftc -emit-symbol-graph-dir \
-Xswiftc .build/symbol-graphs \
&& swift-docc/.build/release/docc convert Sources/SwiftCurrent/Documentation.docc \
--fallback-display-name SwiftCurrent \
--fallback-bundle-identifier com.wwt.SwiftCurrent \
--fallback-bundle-version 0.0.0 \
--additional-symbol-graph-dir \
.build/symbol-graphs \
--transform-for-static-hosting \
--hosting-base-path /SwiftCurrent/"$tag" \
--output-path docs-out/"$tag" \
&& echo "✅ Documentation generated for "$tag" release." \
|| echo "⚠️ Documentation skipped for "$tag".";
fi;
done
- name: Fix permissions
run: 'sudo chown --recursive $USER docs-out'
- name: Publish documentation to GitHub Pages
uses: JamesIves/github-pages-deploy-action@4.1.7
with:
branch: gh-pages
folder: docs-out
single-commit: true
That gave us Docc documentation for just the SwiftCurrent target hosted in GitHub pages, which is a great first step. However, we had trouble getting the _UIKit and _SwiftUI targets to get docc'd without jumping through some hoops.
When Swift 5.6 and/or Xcode 13.3 get released, I think we'll have more flexibility. I've cobbled together the beginnings of a macOS hosted GitHub action that may get us up and running when they are released. More work will undoubtedly be necessary to get this working. I just couldn't test it until Xcode 13.3 gets released.
name: Documentation
on:
push:
branches:
- main
workflow_dispatch:
jobs:
build:
runs-on: macos-latest
steps:
- uses: maxim-lobanov/setup-xcode@v1
with:
xcode-version: '13.3.0-beta'
- name: Checkout Package
uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Checkout gh-pages Branch
uses: actions/checkout@v2
with:
ref: gh-pages
path: docs-out
- name: Build documentation
run: >
rm -rf docs-out/.git;
rm -rf docs-out/main;
for target in $(echo "SwiftCurrent"; echo "SwiftCurrent_SwiftUI");
do
echo "Generating documentation for "$target".";
git checkout main;
swift package \
--allow-writing-to-directory docs-out/main \
generate-documentation \
--target "$target" \
--disable-indexing \
--transform-for-static-hosting \
--hosting-base-path SwiftCurrent/main
--output-path docs-out/main
done
- name: Fix permissions
run: 'sudo chown --recursive $USER docs-out'
- name: Publish documentation to GitHubPages
uses: JamesIves/github-pages-deploy-action@4.1.7
with:
branch: gh-pages
folder: docs-out
single-commit: true
Locally, using the Xcode 13.3-beta3 version, I can run:
xcodebuild docbuild -scheme SwiftCurrent -destination generic/platform=iOS OTHER_DOCC_FLAGS="--transform-for-static-hosting --hosting-base-path SwiftCurrent/main" DOCC_OUTPUT_DIR=./docs
to generate GitHub pages-host able docc documentation. (In order to also document our _SwiftUI target, we'd need to add that to our SwiftCurrent scheme)
Also newly available alongside Swift 5.6 is the DocC swift package plugin, which enables an additional command-line syntax:
swift package --allow-writing-to-directory docs generate-documentation --target SwiftCurrent --disable-indexing --transform-for-static-hosting --hosting-base-path SwiftCurrent/main --output-path docs
Stay tuned...
Xcode 14 to the rescue?
I wish...we can host it on GitHub pages now but it still can't handle multiple targets. So our docs would be disconnected, but Jazzy is giving us all modules joined.
Update on this, there's movement/discussion about a real implementation of DocC supporting multiple targets: https://forums.swift.org/t/combined-documentation-of-multiple-targets