From 789c1bff21e562d8912a5616455a817da4caa288 Mon Sep 17 00:00:00 2001 From: Andrew Watt Date: Thu, 1 May 2025 17:54:06 -0700 Subject: [PATCH] Link to new Swift API docs --- .github/workflows/update-docs.yml | 48 +-------------------- RELEASING.md | 42 ++---------------- deploy_website.sh | 71 ++----------------------------- mkdocs.yml | 6 +-- 4 files changed, 9 insertions(+), 158 deletions(-) diff --git a/.github/workflows/update-docs.yml b/.github/workflows/update-docs.yml index e051b60cb..cdf33736f 100644 --- a/.github/workflows/update-docs.yml +++ b/.github/workflows/update-docs.yml @@ -11,10 +11,6 @@ on: description: 'Kotlin Git ref to publish' default: 'main' required: true - swift-ref: - description: 'Swift Git ref to publish' - default: 'main' - required: true docs-branch: description: 'Branch name for updated documentation to be published' required: true @@ -37,33 +33,6 @@ jobs: ref: ${{ github.event.inputs.kotlin-ref }} path: 'workflow-kotlin' - - name: Check out Swift repo - uses: actions/checkout@v3 - with: - repository: 'square/workflow-swift' - ref: ${{ github.event.inputs.swift-ref }} - path: 'workflow-swift' - - # Ruby Gems - - name: Load gem cache - uses: actions/cache@v3 - with: - path: workflow-swift/.bundle - key: gems-${{ hashFiles('workflow-swift/Gemfile.lock') }} - - - name: Set up Swift environment - run: | - # Set global bundle path so it gets used by build_swift_docs.sh running in the nested repo as well. - cd workflow-swift - bundle config --global path "$(pwd)/.bundle" - bundle check || bundle install - - # Don't need to run pod gen, the website script does that itself. - brew install sourcedocs - - # Use Xcode - sudo xcode-select -s /Applications/Xcode_15.1.app - # Docs dependencies - name: Set up Python uses: actions/setup-python@v4 @@ -82,20 +51,6 @@ jobs: distribution: 'zulu' java-version: 17 - # Build Swift docs - - name: Build Swift docs - run: | - mkdir -p workflow/docs/swift/api - - cd workflow-swift - bundle exec pod gen Development.podspec - cd gen/Development - - sourcedocs generate --output-folder "../../../workflow/docs/swift/api/Workflow" -- -scheme Workflow -workspace Development.xcworkspace - sourcedocs generate --output-folder "../../../workflow/docs/swift/api/WorkflowUI" -- -scheme WorkflowUI -workspace Development.xcworkspace - sourcedocs generate --output-folder "../../../workflow/docs/swift/api/WorkflowTesting" -- -scheme WorkflowTesting -workspace Development.xcworkspace - sourcedocs generate --output-folder "../../../workflow/docs/swift/api/WorkflowReactiveSwift" -- -scheme WorkflowReactiveSwift -workspace Development.xcworkspace - # Build Kotlin docs - name: Build Kotlin docs run: | @@ -127,7 +82,6 @@ jobs: run: | # Get the source repo SHAs KOTLIN_REF=$(git --git-dir workflow-kotlin/.git log -1 --format='%H') - SWIFT_REF=$(git --git-dir workflow-swift/.git log -1 --format='%H') cd workflow-publish git checkout -b ${{ github.event.inputs.docs-branch }} @@ -137,5 +91,5 @@ jobs: # Commit and push git add . - git commit -m "Update documentation" -m "Docs built from square/workflow-kotlin@$KOTLIN_REF and square/workflow-swift@$SWIFT_REF" + git commit -m "Update documentation" -m "Docs built from square/workflow-kotlin@$KOTLIN_REF" git push origin HEAD:${{ github.event.inputs.docs-branch }} diff --git a/RELEASING.md b/RELEASING.md index 8d49e12d9..4fd5ed1ee 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -12,8 +12,7 @@ consists of three parts: 1. Kotlin API reference: Kdoc embedded in Kotlin source files is converted to GitHub-flavored Markdown by Dokka and then included in the statically-generated website. 1. Swift API reference: Markup comments from Swift files are converted Markdown by - [Sourcedocs](https://github.com/eneko/SourceDocs) and then included in the statically-generated - website. + [DocC](https://www.swift.org/documentation/docc/) and then published independently at [square.github.io/workflow-swift/documentation](https://square.github.io/workflow-swift/documentation). **Note: The documentation site is automatically built and deployed whenever a version tag is pushed. You only need these steps if you want to work on the site locally.** @@ -32,44 +31,9 @@ cd kotlin ./gradlew dokka ``` -#### Swift: Sourcedocs +#### Swift: DocC -Sourcedocs generates a Markdown site from Swift files. You need Ruby, rubygems, -bundler (2.x), Xcode 10.2+, CocoaPods, and of course Sourcedocs itself, to run it. Assuming you've -already got Xcode, Ruby, and rubygems set up, install the rest of the dependencies: - -```bash -gem install bundler cocoapods -brew install sourcedocs -``` - -You will also need a checkout of the Swift repo: - -```bash -git clone https://github.com/square/workflow-swift.git -cd workflow-swift -``` - -Then generate an Xcode project before running Sourcedocs: - -```bash -cd Samples/SampleApp/ -bundle exec pod install -# If this is your first time running CocoaPods, that will fail and you'll need to run this instead: -#bundle exec pod install --repo-update -``` - -You can manually generate the docs to verify everything is working correctly by running: - -```bash -#cd Samples/SampleApp/ -sourcedocs generate -- -scheme Workflow -workspace SampleApp.xcworkspace -sourcedocs generate -- -scheme WorkflowUI -workspace SampleApp.xcworkspace -sourcedocs generate -- -scheme WorkflowTesting -workspace SampleApp.xcworkspace -``` - -Note that currently sourcedocs only supports Xcode 10, if you run it with Xcode 11 you might see -an error about Catalyst and only empty READMEs will get generated. +The Swift documentation is published by CI in the Swift repo and linked from the cross-platform Workflow docs. For info on how to generate the Swift docs locally, check out [the workflow-swift repo](https://github.com/square/workflow-swift). #### mkdocs diff --git a/deploy_website.sh b/deploy_website.sh index 38ad7d8be..7e92aa0e0 100755 --- a/deploy_website.sh +++ b/deploy_website.sh @@ -22,21 +22,18 @@ # pip install -r requirements.txt # Preview the site as you're editing it with: # mkdocs serve -# It also uses CocoaPods and Sourcedocs to build the Swift docs. -# See .buildscript/build_swift_docs.sh for setup info. # -# Usage deploy_website.sh --kotlin-ref SHA_OR_REF_TO_DEPLOY --swift-ref SHA_OR_REF_TO_DEPLOY +# Usage deploy_website.sh --kotlin-ref SHA_OR_REF_TO_DEPLOY # Set the DRY_RUN environment variable to any non-null value to skip the actual deploy. # A custom username/password can be used to authenticate to the git repo by setting # the GIT_USERNAME and GIT_PASSWORD environment variables. # -# E.g. to test the script: DRY_RUN=true ./deploy_website.sh --kotlin-ref main --swift-ref main +# E.g. to test the script: DRY_RUN=true ./deploy_website.sh --kotlin-ref main # Automatically exit the script on error. set -e KOTLIN_REPO=square/workflow-kotlin -SWIFT_REPO=square/workflow-swift if [ -z "$WORKFLOW_GOOGLE_ANALYTICS_KEY" ]; then echo "Must set WORKFLOW_GOOGLE_ANALYTICS_KEY to deploy." >&2 @@ -92,80 +89,20 @@ function buildKotlinDocs() { echo "Kotlin docs finished." } -# This function uses SourceDocs. -# https://github.com/eneko/SourceDocs -# brew install sourcedocs -# It requires Xcode (minimum 10.2) to run. -# Note if you get error messages from pod gen, try running: -# bundle exec pod repo update -function buildSwiftDocs() { - local deployRef="$1" - local targetDir="$2" - local workingDir=deploy-swift - local workflowSchemes=(Workflow WorkflowUI WorkflowTesting WorkflowReactiveSwift) - - if [[ -z "$deployRef" ]]; then echo "buildSwiftDocs: Must pass deploy ref as first arg" >&2; exit 1; fi - if [[ -z "$targetDir" ]]; then echo "buildSwiftDocs: Must pass target dir as second arg" >&2; exit 1; fi - - if [[ -d "$workingDir" ]]; then - echo "Removing old working directory $workingDir..." - rm -rf "$workingDir" - fi - - echo "Shallow-cloning $SWIFT_REPO from $deployRef into $workingDir..." - git clone --depth 1 --branch $deployRef $(getAuthenticatedRepoUrl $SWIFT_REPO) $workingDir - - echo "Building Swift docs..." - pushd $workingDir - - bundle exec pod gen Development.podspec - cd gen/Development - - # Clean the target dir first. - [[ -d "$targetDir" ]] && rm -rf "$targetDir" - mkdir -p "$targetDir" - - # Generate the API docs. - for scheme in $workflowSchemes; do - local outputDir="$targetDir/$scheme" - echo "Generating sourcedocs for scheme $scheme to $outputDir..." - sourcedocs generate \ - --output-folder "$outputDir" \ - -- \ - -scheme $scheme \ - -workspace Development.xcworkspace - done - popd - - echo "Removing working directory..." - rm -rf "$workingDir" - - echo "Swift docs finished." -} - # Process arguments. See man zshmodules. -zparseopts -A refs -kotlin-ref: -swift-ref: +zparseopts -A refs -kotlin-ref: KOTLIN_REF=${refs[--kotlin-ref]} -SWIFT_REF=${refs[--swift-ref]} if [[ -z $KOTLIN_REF ]]; then echo "Missing --kotlin-ref argument" >&2 exit 1 fi -if [[ -z "$SWIFT_REF" ]]; then - echo "Missing --swift-ref argument" >&2 - exit 1 -fi echo "Deploying from $KOTLIN_REPO at $KOTLIN_REF" -echo "Deploying from $SWIFT_REPO at $SWIFT_REF" echo "Building Kotlin docs…" buildKotlinDocs $KOTLIN_REF "$(pwd)/docs/kotlin/api" -echo "Building Swift docs…" -buildSwiftDocs $SWIFT_REF "$(pwd)/docs/swift/api" - # Push the new files up to GitHub. -mkdocsMsg="Deployed docs using mkdocs {version} and script from {sha} from ${KOTLIN_REPO}@$KOTLIN_REF and ${SWIFT_REPO}@$SWIFT_REF" +mkdocsMsg="Deployed docs using mkdocs {version} and script from {sha} from ${KOTLIN_REPO}@$KOTLIN_REF" if [ -n "$DRY_RUN" ]; then echo "DRY_RUN enabled, building mkdocs but skipping gh-deploy and push…" mkdocs build diff --git a/mkdocs.yml b/mkdocs.yml index 7c8427bfc..1028c5793 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -102,11 +102,7 @@ nav: - 'Kotlin Samples 🔗': https://github.com/square/workflow-kotlin/tree/main/samples - 'API Reference': - 'Kotlin 🔗': 'kotlin/api/htmlMultiModule' - - 'Swift API': - - 'Workflow ': 'swift/api/Workflow/README.md' - - 'WorkflowReactiveSwift': 'swift/api/WorkflowReactiveSwift/README.md' - - 'WorkflowUI ': 'swift/api/WorkflowUI/README.md' - - 'WorkflowTesting ': 'swift/api/WorkflowTesting/README.md' + - 'Swift 🔗': https://square.github.io/workflow-swift/documentation - 'Glossary': 'glossary.md' - 'FAQ': faq.md - 'Pre-1.0 Resources': historical.md