Update CI.yml, Makefile, Package.swift to support docc

Author: wei18

.github/workflows/CI.yml

@@ -1,10 +1,13 @@
 name: CI
 
-on: [push]
+on: 
+  push:
+    branches:
+      - main
 
 jobs:
 
-  test:
+  Test:
     name: Swift ${{ matrix.swift }} on ${{ matrix.os }}
     strategy:
       matrix:
@@ -21,4 +24,38 @@ jobs:
           os: ${{ matrix.os }}
 
       - run: swift build
-      - run: swift test
+      - run: swift test
+
+  # Package.swift uses GITHUB_JOB to add docc dependency
+  BuildDocC:
+    strategy:
+      matrix:
+        os:
+          - ubuntu-latest
+          # - macos-latest
+        swift: ["5.9"]
+    runs-on: ${{ matrix.os }}
+    env:
+      GITHUB_PAGES: "true"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/workflows/actions/setup
+      - run: make .build/docs
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: .build/docs
+
+  DeployDocC:
+    needs: BuildDocC
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

Makefile

@@ -20,4 +20,19 @@ Sources/%/openapi.yml: Submodule
 	git commit -m "Relink $@" || true
 
 .PHONY: install
-install: $(OPENAPI_FILES)
+install: $(OPENAPI_FILES)
+
+.build/docs: ## Need env GITHUB_PAGES is created as 'true'
+	swift package --allow-writing-to-directory $@ generate-documentation \
+	--target GitHubRestAPISwiftOpenAPI \
+	--disable-indexing \
+	--output-path $@ \
+	--transform-for-static-hosting \
+	--hosting-base-path github-rest-api-swift-openapi;
+
+.PHONY: help
+.SILENT: help
+help:
+	echo -----------------------------------------------------------------------
+	awk 'BEGIN {FS = ":.*##"; printf "Usage:\n  make \033[36m\033[0m\n"} /^[$$()% 0-9a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+	echo -----------------------------------------------------------------------

Package.swift

@@ -2,6 +2,7 @@
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import PackageDescription
+import Foundation
 
 /// The generator supports filtering the OpenAPI document prior to generation, 
 /// which can be useful when generating client code for a subset of a large API, 
@@ -74,6 +75,11 @@ enum GitHubRestAPIOpenAPITag: String, CaseIterable {
     }
 }
 
+let gitHubRestAPISwiftOpenAPITarget: PackageDescription.Target = .target(
+    name: "GitHubRestAPISwiftOpenAPI",
+    dependencies: GitHubRestAPIOpenAPITag.allCases.map { .target(name: $0.rawValue) }
+)
+
 let package = Package(
     name: "GitHubRestAPISwiftOpenAPI",
     platforms: [.macOS(.v10_15)],
@@ -84,6 +90,16 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-openapi-urlsession", from: "1.0.0"),
     ],
     targets: GitHubRestAPIOpenAPITag.allCases.map(\.target) + [
-        GitHubRestAPIOpenAPITag.users.testTarget
+        gitHubRestAPISwiftOpenAPITarget,
+        GitHubRestAPIOpenAPITag.users.testTarget,
     ]
 )
+
+let isBuildDocC = ProcessInfo.processInfo.environment["GITHUB_PAGES"] == "true"
+
+// swift-docs is not needed for package users
+if isBuildDocC {
+    package.dependencies += [
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
+    ]
+}

Sources/GitHubRestAPISwiftOpenAPI/File.swift

@@ -0,0 +1,6 @@
+//
+//  File.swift
+//  
+//
+//  Created by zwc on 2023/12/31.
+//