From a7b063b5a6bbb0bab570ff79a37f8ed2cdfbd500 Mon Sep 17 00:00:00 2001 From: Franz Busch Date: Thu, 21 Sep 2023 11:15:55 +0200 Subject: [PATCH] Add support for the Swift package index # Motivation We had some scripts around to generate docs for this package but all of our other packages are now providing documentation on the Swift package index. # Modification This removes the old script to generate documentation and adds an `.spi.yml` file. Furthermore, I removed the conditional dependency on the docc plugin which we are unconditionally depending on in most of our other packages like NIO. --- .spi.yml | 4 ++ Package.swift | 20 ++------ Package@swift-5.7.swift | 20 ++------ bin/update-gh-pages-documentation-site | 71 -------------------------- 4 files changed, 12 insertions(+), 103 deletions(-) create mode 100644 .spi.yml delete mode 100755 bin/update-gh-pages-documentation-site diff --git a/.spi.yml b/.spi.yml new file mode 100644 index 00000000..2a779cf6 --- /dev/null +++ b/.spi.yml @@ -0,0 +1,4 @@ +version: 1 +builder: + configs: + - documentation_targets: [AsyncAlgorithms] diff --git a/Package.swift b/Package.swift index afc3bcaa..2932e199 100644 --- a/Package.swift +++ b/Package.swift @@ -13,7 +13,10 @@ let package = Package( products: [ .library(name: "AsyncAlgorithms", targets: ["AsyncAlgorithms"]), ], - dependencies: [.package(url: "https://github.com/apple/swift-collections.git", .upToNextMajor(from: "1.0.4"))], + dependencies: [ + .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.4"), + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), + ], targets: [ .target( name: "AsyncAlgorithms", @@ -46,18 +49,3 @@ let package = Package( ), ] ) - -#if canImport(Darwin) -import Darwin -let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil -#elseif canImport(Glibc) -import Glibc -let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil -#else -let buildingDocs = false -#endif - -// Only require the docc plugin when building documentation -package.dependencies += buildingDocs ? [ - .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), -] : [] diff --git a/Package@swift-5.7.swift b/Package@swift-5.7.swift index 56417e84..7c488af0 100644 --- a/Package@swift-5.7.swift +++ b/Package@swift-5.7.swift @@ -16,7 +16,10 @@ let package = Package( .library(name: "_CAsyncSequenceValidationSupport", type: .static, targets: ["AsyncSequenceValidation"]), .library(name: "AsyncAlgorithms_XCTest", targets: ["AsyncAlgorithms_XCTest"]), ], - dependencies: [.package(url: "https://github.com/apple/swift-collections.git", .upToNextMajor(from: "1.0.4"))], + dependencies: [ + .package(url: "https://github.com/apple/swift-collections.git", from: "1.0.4"), + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), + ], targets: [ .target( name: "AsyncAlgorithms", @@ -34,18 +37,3 @@ let package = Package( dependencies: ["AsyncAlgorithms", "AsyncSequenceValidation", "AsyncAlgorithms_XCTest"]), ] ) - -#if canImport(Darwin) -import Darwin -let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil -#elseif canImport(Glibc) -import Glibc -let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil -#else -let buildingDocs = false -#endif - -// Only require the docc plugin when building documentation -package.dependencies += buildingDocs ? [ - .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"), -] : [] diff --git a/bin/update-gh-pages-documentation-site b/bin/update-gh-pages-documentation-site deleted file mode 100755 index 0c1e59aa..00000000 --- a/bin/update-gh-pages-documentation-site +++ /dev/null @@ -1,71 +0,0 @@ -#!/bin/bash -# -# This source file is part of the Swift.org open source project -# -# Copyright (c) 2022 Apple Inc. and the Swift project authors -# Licensed under Apache License v2.0 with Runtime Library Exception -# -# See https://swift.org/LICENSE.txt for license information -# See https://swift.org/CONTRIBUTORS.txt for Swift project authors -# -# Updates the GitHub Pages documentation site thats published from the 'docs' -# subdirectory in the 'gh-pages' branch of this repository. -# -# This script should be run by someone with commit access to the 'gh-pages' branch -# at a regular frequency so that the documentation content on the GitHub Pages site -# is up-to-date with the content in this repo. -# - -export BUILDING_FOR_DOCUMENTATION_GENERATION=1 - -set -eu - -# A `realpath` alternative using the default C implementation. -filepath() { - [[ $1 = /* ]] && echo "$1" || echo "$PWD/${1#./}" -} - -SWIFT_ASYNC_ALGORITHMS_ROOT="$(dirname $(dirname $(filepath $0)))" - -ASYNC_ALGORITHMS_BUILD_DIR="$SWIFT_ASYNC_ALGORITHMS_ROOT"/.build/async-algorithms-gh-pages-build - -# Set current directory to the repository root -cd "$SWIFT_ASYNC_ALGORITHMS_ROOT" - -# Use git worktree to checkout the gh-pages branch of this repository in a gh-pages sub-directory -git fetch -git worktree add --checkout gh-pages origin/gh-pages - -# Pretty print DocC JSON output so that it can be consistently diffed between commits -export DOCC_JSON_PRETTYPRINT="YES" - -# Generate documentation for the 'AsyncAlgorithms' target and output it -# to the /docs subdirectory in the gh-pages worktree directory. -swift package \ - --allow-writing-to-directory "$SWIFT_ASYNC_ALGORITHMS_ROOT/gh-pages/docs" \ - generate-documentation \ - --target AsyncAlgorithms \ - --disable-indexing \ - --transform-for-static-hosting \ - --hosting-base-path swift-async-algorithms \ - --output-path "$SWIFT_ASYNC_ALGORITHMS_ROOT/gh-pages/docs" - -# Save the current commit we've just built documentation from in a variable -CURRENT_COMMIT_HASH=`git rev-parse --short HEAD` - -# Commit and push our changes to the gh-pages branch -cd gh-pages -git add docs - -if [ -n "$(git status --porcelain)" ]; then - echo "Documentation changes found. Commiting the changes to the 'gh-pages' branch and pushing to origin." - git commit -m "Update GitHub Pages documentation site to $CURRENT_COMMIT_HASH" - git push origin HEAD:gh-pages -else - # No changes found, nothing to commit. - echo "No documentation changes found." -fi - -# Delete the git worktree we created -cd .. -git worktree remove gh-pages