sersoft-gmbh / swifty-docs-action Goto Github PK

View Code? Open in Web Editor NEW

11.0 3.0 1.0 507 KB

A GitHub Action that generates documentation for a Swift package using docc.

License: Apache License 2.0

Swift 35.20% TypeScript 64.80%

github-actions docc swift xcode

swifty-docs-action's Introduction

Swift Package Documentation Generator

This action generates documentation for a Swift package using docc.

Important: The package must use the Swift-DocC Plugin unless xcodebuild is used!

Note: As of version 2, this action uses docc instead of jazzy! Use @v1 to use jazzy.

Inputs

`package-path`

The path to the package.
Required. Defaults to ${{github.workspace}}.

`package-version`

The version to use for this package.

`enable-inherited-docs`

Whether to enable inherited docs. Defaults to false.

`enable-index-buildiung`

Enable index building. Defaults to false.

`transform-for-static-hosting`

Enables the static hosting transformation. Defaults to false.

`hosting-base-path`

The hosting base path to use.

`other-docc-arguments`

Further (newline-separated) docc arguments.

`targets`

A list of targets separated by newline. If not given, all targets are built.
This is ignored if use-xcodebuild is true!

`use-xcodebuild`

Tells the action to use xcodebuild (instead of swift package). Use xcodebuild-scheme and xcodebuild-destination to further customize the xcodebuild invocation.
Defaults to false.
Note: This parameter is only evaluated when running on macOS.

`xcodebuild-scheme`

The scheme to use for the xcodebuild invocation. Only used if use-xcodebuild is true.
Note: This parameter is only evaluated when running on macOS.

`xcodebuild-destination`

The destination to use for the xcodebuild invocation. Only used if use-xcodebuild is true.
Note: This parameter is only evaluated when running on macOS.

`other-xcodebuild-arguments`

Further (newline-separated) xcodebuild arguments.

`output`

The path to the output directory.

Example Usage

Use the following snippet in a Swift package repository to generate documentation for all products of your Swift package:

uses: sersoft-gmbh/swifty-docs-action@v3
with:
  output: docs

swifty-docs-action's People

Contributors

Stargazers

Watchers

Forkers

callummccoll

swifty-docs-action's Issues

Cannot generate docs for multiple targets?

Good chance I am doing something wrong.

Workfow:

...
jobs:
  generate-and-publish-docs:
    runs-on: macOS-latest
    steps:
      - name: Get da Code
        uses: actions/checkout@v4
      - name: Setup Swift
        uses: swift-actions/[email protected]
        with:
          swift-version: '5.9'
      - name: Swift Package Documentation Generator
        uses: sersoft-gmbh/[email protected]
        with:
          transform-for-static-hosting: true
          hosting-base-path: swift-gopher
          targets: |
            GopherHelpers
            swift-gopher
            swiftGopherClient
          output: docs
      - name: Upload Docs
        uses: EndBug/add-and-commit@v9 
        with:
          add: "docs"
          message: Update Documentation
          committer_name: GitHub Actions
          committer_email: [email protected]

I enabled debug mode on the workflow here

The command is definitely parsing the targets correctly:

  /Users/runner/hostedtoolcache/swift-macOS/5.9/x64/usr/bin/swift package --allow-writing-to-directory /Users/runner/work/swift-gopher/swift-gopher/docs generate-documentation --target GopherHelpers --target swift-gopher --target swiftGopherClient --disable-indexing --transform-for-static-hosting --hosting-base-path swift-gopher --output-path /Users/runner/work/swift-gopher/swift-gopher/docs

...

  [35/37] Compiling swiftGopherClient gopherClient.swift
  [36/37] Emitting module swiftGopherClient
  [37/37] Compiling swiftGopherClient gopherRequestResponseHandler.swift
  Build complete! (13.74s)
  Generating documentation for 'GopherHelpers'...
  Converting documentation...
  Conversion complete! (0.30s)
  Generated DocC archive at '/Users/runner/work/swift-gopher/swift-gopher/docs'
  
  Generating documentation for 'swift-gopher'...
  Converting documentation...
  Conversion complete! (0.20s)
  Generated DocC archive at '/Users/runner/work/swift-gopher/swift-gopher/docs'
  
  Generating documentation for 'swiftGopherClient'...
  Converting documentation...
  Conversion complete! (0.13s)
  Generated DocC archive at '/Users/runner/work/swift-gopher/swift-gopher/docs'
  
  Multiple DocC archives generated at '/Users/runner/work/swift-gopher/swift-gopher/.build/plugins/Swift-DocC/outputs'
  ::endgroup::

But, https://github.com/navanchauhan/swift-gopher/tree/master/docs/documentation/ only has one target

Error while generating JSON docs

This error happens when the CI runs.

Failed to generate documentation
Error: The process '/usr/local/bin/sourcekitten' failed with exit code 1

'/usr/bin/xcodebuild' failed

I got this error when using xcodebuild

Error: The process '/usr/bin/xcodebuild' failed with exit code 66

configuration is like this

jobs:
  build_docC:
    runs-on: macos-14
    steps:
    - name: build static site
      uses: sersoft-gmbh/[email protected]
      with:
          use-xcodebuild: 'true'
          xcodebuild-scheme: 'MegaX'
          xcodebuild-destination: 'generic/platform=iOS'
          output: docs

sersoft-gmbh / swifty-docs-action Goto Github PK

swifty-docs-action's Introduction

Swift Package Documentation Generator

Inputs

package-path

package-version

enable-inherited-docs

enable-index-buildiung

transform-for-static-hosting

hosting-base-path

other-docc-arguments

targets

use-xcodebuild

xcodebuild-scheme

xcodebuild-destination

other-xcodebuild-arguments

output