From fc46564349ff5a8b18c4d56f35553961fab81b78 Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 01:42:06 +0000 Subject: [PATCH 1/8] Remove unresolvable references --- Sources/BinaryParseKit/MatchableProtocols.swift | 1 - 1 file changed, 1 deletion(-) diff --git a/Sources/BinaryParseKit/MatchableProtocols.swift b/Sources/BinaryParseKit/MatchableProtocols.swift index 08db8cf..6e5f41d 100644 --- a/Sources/BinaryParseKit/MatchableProtocols.swift +++ b/Sources/BinaryParseKit/MatchableProtocols.swift @@ -12,7 +12,6 @@ public protocol Matchable { /// A protocol for types that conform to `RawRepresentable` and `Matchable`. /// It provides a default implementation for `RawRepresentable` whose `RawValue` conforms to `Matchable`. -/// - SeeAlso: ``bytesToMatch()-1kmth`` public protocol MatchableRawRepresentable: RawRepresentable, Matchable {} /// Default implementation of `bytesToMatch()` for `MatchableRawRepresentable` where `RawValue` conforms to `Matchable`. From 1fdf3c6bb49e3fd5a5686e5bb9a7a3111a454ee6 Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 01:42:16 +0000 Subject: [PATCH 2/8] Add documentation generation --- Package.resolved | 20 +++++++++++++++++++- Package.swift | 1 + 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/Package.resolved b/Package.resolved index 39f5a9d..4e7fc7c 100644 --- a/Package.resolved +++ b/Package.resolved @@ -1,5 +1,5 @@ { - "originHash" : "8bbc373bcf8db755460e717ab6cbb79a66408d9aee27c6d562fa53fe12e22529", + "originHash" : "9238a5eff43ac33dc7a148b7c3163fffc867bb0cb4bc7d811ac286cc2c3118d4", "pins" : [ { "identity" : "swift-binary-parsing", @@ -19,6 +19,24 @@ "version" : "1.1.6" } }, + { + "identity" : "swift-docc-plugin", + "kind" : "remoteSourceControl", + "location" : "https://github.com/apple/swift-docc-plugin", + "state" : { + "revision" : "3e4f133a77e644a5812911a0513aeb7288b07d06", + "version" : "1.4.5" + } + }, + { + "identity" : "swift-docc-symbolkit", + "kind" : "remoteSourceControl", + "location" : "https://github.com/swiftlang/swift-docc-symbolkit", + "state" : { + "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34", + "version" : "1.0.0" + } + }, { "identity" : "swift-syntax", "kind" : "remoteSourceControl", diff --git a/Package.swift b/Package.swift index 8edfd36..0b1098e 100644 --- a/Package.swift +++ b/Package.swift @@ -25,6 +25,7 @@ let package = Package( url: "https://github.com/apple/swift-collections.git", .upToNextMinor(from: "1.1.0"), ), + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.5"), ], targets: [ .macro( From 3f8999f204b9f48f70d29880d9acaca6f9538aaa Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 01:58:31 +0000 Subject: [PATCH 3/8] Add CI for doc deploying --- .github/workflows/deploy-docc.yml | 48 +++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 .github/workflows/deploy-docc.yml diff --git a/.github/workflows/deploy-docc.yml b/.github/workflows/deploy-docc.yml new file mode 100644 index 0000000..0ff548d --- /dev/null +++ b/.github/workflows/deploy-docc.yml @@ -0,0 +1,48 @@ +name: Deploy DocC +on: + push: + branches: + - main + pull_request: + branches: + - main +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: "pages" + cancel-in-progress: true +jobs: + build: + name: Build DocC Documentation + runs-on: macOS-26 + env: + DEVELOPER_DIR: "/Applications/Xcode_26.0.app/Contents/Developer" + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Swift Version + run: xcrun swift --version + - name: Build DocC + run: | + swift package --allow-writing-to-directory ./docs \ + generate-documentation \ + --target BinaryParseKit \ + --output-path ./docs \ + --transform-for-static-hosting + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 + with: + path: ./docs + deploy: + name: Deploy to GitHub Pages + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From d9f4e1fd8220426f166716ef99de46573c40ddc7 Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 02:01:06 +0000 Subject: [PATCH 4/8] Add docs output to `.gitignore` --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index c62b3f3..aec27b6 100644 --- a/.gitignore +++ b/.gitignore @@ -69,3 +69,5 @@ fastlane/report.xml fastlane/Preview.html fastlane/screenshots/**/*.png fastlane/test_output + +docs/ From 5234faff63032a836732dc59b9bd999a2526c9e1 Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 02:20:12 +0000 Subject: [PATCH 5/8] xcodebuid --- .github/workflows/deploy-docc.yml | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/.github/workflows/deploy-docc.yml b/.github/workflows/deploy-docc.yml index 0ff548d..19ffaf4 100644 --- a/.github/workflows/deploy-docc.yml +++ b/.github/workflows/deploy-docc.yml @@ -26,11 +26,18 @@ jobs: run: xcrun swift --version - name: Build DocC run: | - swift package --allow-writing-to-directory ./docs \ - generate-documentation \ - --target BinaryParseKit \ - --output-path ./docs \ - --transform-for-static-hosting + xcodebuild docbuild \ + -scheme BinaryParseKit-Package \ + -destination 'generic/platform=macOS' \ + -derivedDataPath ./DerivedData + + # Find the generated .doccarchive + DOCC_ARCHIVE=$(find ./DerivedData -name "BinaryParseKit.doccarchive" | head -n 1) + + # Process the archive for static hosting + xcrun docc process-archive \ + transform-for-static-hosting "$DOCC_ARCHIVE" \ + --output-path ./docs - name: Upload artifact uses: actions/upload-pages-artifact@v4 with: From 82f3691edcdcd116512a0dfcdde27e9eed60787b Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 02:38:35 +0000 Subject: [PATCH 6/8] Use 26.1 --- .github/workflows/deploy-docc.yml | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/.github/workflows/deploy-docc.yml b/.github/workflows/deploy-docc.yml index 19ffaf4..a207d60 100644 --- a/.github/workflows/deploy-docc.yml +++ b/.github/workflows/deploy-docc.yml @@ -18,7 +18,7 @@ jobs: name: Build DocC Documentation runs-on: macOS-26 env: - DEVELOPER_DIR: "/Applications/Xcode_26.0.app/Contents/Developer" + DEVELOPER_DIR: "/Applications/Xcode_26.1.app/Contents/Developer" steps: - name: Checkout uses: actions/checkout@v4 @@ -26,18 +26,12 @@ jobs: run: xcrun swift --version - name: Build DocC run: | - xcodebuild docbuild \ - -scheme BinaryParseKit-Package \ - -destination 'generic/platform=macOS' \ - -derivedDataPath ./DerivedData - - # Find the generated .doccarchive - DOCC_ARCHIVE=$(find ./DerivedData -name "BinaryParseKit.doccarchive" | head -n 1) - - # Process the archive for static hosting - xcrun docc process-archive \ - transform-for-static-hosting "$DOCC_ARCHIVE" \ - --output-path ./docs + xcrun swift build + xcrun swift package --allow-writing-to-directory ./docs \ + generate-documentation \ + --target BinaryParseKit \ + --output-path ./docs \ + --transform-for-static-hosting - name: Upload artifact uses: actions/upload-pages-artifact@v4 with: From c9c5b13d9ba2b139d8b20dde2e68875d4df8b657 Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 03:08:23 +0000 Subject: [PATCH 7/8] Add docc --- README.md | 2 +- .../Documentation.docc/Articles/Guide.md | 1 + .../Documentation.docc/BinaryParseKit.md | 53 +++++++++++++++++++ 3 files changed, 55 insertions(+), 1 deletion(-) create mode 120000 Sources/BinaryParseKit/Documentation.docc/Articles/Guide.md create mode 100644 Sources/BinaryParseKit/Documentation.docc/BinaryParseKit.md diff --git a/README.md b/README.md index 763b4c0..aa21b2f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ A declarative Swift package for parsing binary data using macros, built on top of Apple's [`swift-binary-parsing`](https://github.com/apple/swift-binary-parsing) framework. > [!IMPORTANT] -> This package is currently under active development and its APIs are subjected to drastic changes. +> Warning: This package is currently under active development and its APIs are subjected to drastic changes. ## Features diff --git a/Sources/BinaryParseKit/Documentation.docc/Articles/Guide.md b/Sources/BinaryParseKit/Documentation.docc/Articles/Guide.md new file mode 120000 index 0000000..ff5c796 --- /dev/null +++ b/Sources/BinaryParseKit/Documentation.docc/Articles/Guide.md @@ -0,0 +1 @@ +../../../../README.md \ No newline at end of file diff --git a/Sources/BinaryParseKit/Documentation.docc/BinaryParseKit.md b/Sources/BinaryParseKit/Documentation.docc/BinaryParseKit.md new file mode 100644 index 0000000..7e21394 --- /dev/null +++ b/Sources/BinaryParseKit/Documentation.docc/BinaryParseKit.md @@ -0,0 +1,53 @@ +# ``BinaryParseKit`` + +A powerful Swift package for binary data parsing using macros and protocols. + +## Overview + +BinaryParseKit provides a convenient and type-safe way to parse binary data in Swift. It leverages Swift macros and protocols to automatically generate parsing logic for your data structures, making it easy to work with binary file formats, network protocols, and other binary data sources. + +## Topics + +### Articles + +- + +### Struct Parsing Macros + +- ``ParseStruct()`` +- ``parse()`` +- ``parse(byteCount:)`` +- ``parse(endianness:)`` +- ``parse(byteCount:endianness:)`` +- ``parse(byteCountOf:)`` +- ``parse(byteCountOf:endianness:)`` +- ``parseRest()`` +- ``parseRest(endianness:)`` +- ``skip(byteCount:because:)`` + +### Enum Parsing Macros + +- ``ParseEnum()`` +- ``match()`` +- ``match(byte:)`` +- ``match(bytes:)`` +- ``matchAndTake()`` +- ``matchAndTake(byte:)`` +- ``matchAndTake(bytes:)`` +- ``matchDefault()`` + +### Parsable Protocols + +- ``Parsable`` +- ``EndianParsable`` +- ``SizedParsable`` +- ``EndianSizedParsable`` + +### Matchable Protocols + +- ``Matchable`` +- ``MatchableRawRepresentable`` + +### Error + +- ``BinaryParserKitError`` From 85c570abc7bffd836f5652de93522734403e9715 Mon Sep 17 00:00:00 2001 From: Heyuan Zeng Date: Tue, 11 Nov 2025 03:15:39 +0000 Subject: [PATCH 8/8] Remove PR in docc build --- .github/workflows/deploy-docc.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/deploy-docc.yml b/.github/workflows/deploy-docc.yml index a207d60..bfb20c9 100644 --- a/.github/workflows/deploy-docc.yml +++ b/.github/workflows/deploy-docc.yml @@ -3,9 +3,6 @@ on: push: branches: - main - pull_request: - branches: - - main permissions: contents: read pages: write