From 09fe8cc403ab161abf467f7756c1580018f4133a Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Sun, 5 May 2024 16:43:22 +0200 Subject: [PATCH 1/2] docs: migrated Jazzy to SPM --- .github/workflows/documentation.yml | 22 +++++++-- .jazzy.yaml | 74 ++++++++++++++++++++++++----- 2 files changed, 80 insertions(+), 16 deletions(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 79ccbe7c..776d6be5 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -3,10 +3,14 @@ name: Documentation on: release: types: [published] + pull_request: + branches: + - main workflow_dispatch: jobs: deploy_docs: + name: Generate Documentation runs-on: macos-latest steps: - # Checkout the repository @@ -17,9 +21,19 @@ jobs: with: bundler-cache: true - - # Generate Docs - name: Generate Documentation - run: bundle exec jazzy --config .jazzy.yaml + - # Adapt the default title by adding the reference name from GitHub + name: Patch Title + run: | + ESCAPED_REF_NAME=$(echo "${{ github.ref }}" | sed 's/[\/&]/\\&/g') + sed -i.bak "s/title:\(.*\)/title:\1 ($ESCAPED_REF_NAME)/g" .jazzy.yaml + + - # Generate Documentation + name: Generate + run: | + SDK_PATH=`xcrun --sdk iphonesimulator --show-sdk-path` + SDK_VERSION=`xcrun --sdk iphonesimulator --show-sdk-version` + bundle exec jazzy \ + --build-tool-arguments "--sdk,${SDK_PATH},-Xswiftc,-sdk,-Xswiftc,$SDK_PATH,-Xswiftc,-target,-Xswiftc,arm64-apple-ios${SDK_VERSION}-simulator" - # Small Jazzy fixes for GitHub Pages name: Fix Invalid URLs @@ -29,6 +43,7 @@ jobs: - # Commit newly generated docs name: Commit Documentation Files + if: github.event_name != 'pull_request' run: | cd docs git init @@ -40,6 +55,7 @@ jobs: - # Publish generated docs to the GitHub pages branch name: Push changes uses: ad-m/github-push-action@master + if: github.event_name != 'pull_request' with: directory: docs github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.jazzy.yaml b/.jazzy.yaml index 42d60371..e7613a97 100644 --- a/.jazzy.yaml +++ b/.jazzy.yaml @@ -1,16 +1,64 @@ -author: Philip Niedertscheider -author_url: https://www.github.com/philprime -github_url: https://www.github.com/techprimate/TPPDF -root_url: https://techprimate.github.io/TPPDF/ +# Name of module being documented. module: TPPDF +# Folder to output the HTML docs to output: docs + +# Name of author to attribute in docs +author: Philip Niedertscheider +# Author URL of this project +author_url: https://github.com/philprime +# Copyright markdown rendered at the bottom of the docs pages +copyright: "© 2024 [techprimate GmbH](https://techprimate.com). All rights reserved." +# URL to link from the source host's logo. +source_host_url: https://github.com/techprimate/TPPDF +github_url: https://github.com/techprimate/TPPDF +root_url: https://techprimate.github.io/TPPDF/ + +# Which theme to use. Specify either 'apple' (default), one of the other built-in theme names, or the +# path to your mustache templates and other assets for a custom theme. theme: fullwidth -xcodebuild_arguments: - [ - -workspace, - "Examples.xcworkspace", - -scheme, - "Example iOS (SPM)", - -sdk, - "iphonesimulator", - ] +# Title to display at the top of each page, overriding the default generated from module name and version. +title: TPPDF + +# The SDK for which your code should be built. +sdk: iphonesimulator +# Source file pathnames to be included in documentation. Supports wildcards. +include: Source/** +# Control whether Jazzy uses Swift Package Manager, xcodebuild, or swift-symbolgraph to build the module to be documented. +# By default it uses xcodebuild if there is a .xcodeproj file in the source directory. +swift_build_tool: spm + +# Arguments to forward to xcodebuild, swift build, or sourcekitten. +# +# THESE ARE PROBABLY OUTDATED BUT ARE OVERWRITTEN IN THE CI +# +# You can find the SDK path using: +# +# xcrun --sdk iphonesimulator --show-sdk-path +build_tool_arguments: + - --sdk + - /Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator17.4.sdk + - -Xswiftc + - -target + - -Xswiftc + - arm64-apple-ios17.2-simulator + - -Xswiftc + - -sdk + - -Xswiftc + - /Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator17.4.sdk + +# The base URL on the source host of the project's files, to link from individual declarations. +# For example https://github.com/realm/realm-cocoa/tree/v0.87.1 +# source_host_files_url: '' +# minimum access control level to document +min_acl: public +# Don't document declarations that have no documentation comments. +skip_undocumented: false +# Default text for undocumented symbols. The default is "Undocumented", put "" if no text is required +undocumented_text: Undocumented +# Replace unsafe characters in filenames with an encoded representation. +# This will reduce human readability of some URLs, but may be necessary for projects that +# expose filename-unfriendly functions such as /(_:_:) +use_safe_filenames: true +# Create separate pages for all global declarations (classes, structures, enums etc.) even if they don't have children. +separate_global_declarations: true From cc7c6d3bff2a7de652ee1bea96bc8f14750a6d28 Mon Sep 17 00:00:00 2001 From: Philip Niedertscheider Date: Sun, 5 May 2024 16:48:29 +0200 Subject: [PATCH 2/2] WIP --- .jazzy.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.jazzy.yaml b/.jazzy.yaml index e7613a97..417ed000 100644 --- a/.jazzy.yaml +++ b/.jazzy.yaml @@ -37,15 +37,15 @@ swift_build_tool: spm # xcrun --sdk iphonesimulator --show-sdk-path build_tool_arguments: - --sdk - - /Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator17.4.sdk + - /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator.sdk - -Xswiftc - -target - -Xswiftc - - arm64-apple-ios17.2-simulator + - arm64-apple-ios17.4-simulator - -Xswiftc - -sdk - -Xswiftc - - /Applications/Xcode-15.3.0.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator17.4.sdk + - /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator.sdk # The base URL on the source host of the project's files, to link from individual declarations. # For example https://github.com/realm/realm-cocoa/tree/v0.87.1