Skip to content

Latest commit

 

History

History
78 lines (67 loc) · 3.18 KB

README.md

File metadata and controls

78 lines (67 loc) · 3.18 KB
Raw

Publish Jazzy Docs to Github Pages

A GitHub Action to generate and publish Jazzy documentation for your Swift and/or Objective-C projects.

Assumptions

This Action expects the following to be true:

  • Your workflow runs on macOS
  • You have documentation comments present in your Swift/Objective-C project (otherwise you will be generating a pretty useless website)
  • You have a gh-pages branch in your repository
  • A personal access token with repo scope. The GITHUB_TOKEN available as part of an action will not trigger a Github Pages build. See this discussion thread for more information.

Configuration

Key Description Required
personal_access_token A personal access token with repo scope for pushing documentation to gh-pages branch. See Creating a Personal Access Token for creating the token and Creating and Using Secrets for including secrets to be used in tandem with Github Actions. Yes
config The path to a Jazzy yaml or json configuration file No
args Command line arguments to be passed to Jazzy. See jazzy --help on your local machine for available options No
version The Jazzy version to run. Defaults to latest No

Limitations

This Action will never support the following:

  • Generating and deploying documentation to master or in a docs folder on master
  • Maintain commit history of the gh-pages branch.

This Action does not currently support the following:

  • Specifying both config and args. Any args provided along with config will be ignored.

Usage

Documentation generation can be as minimal as the following:

name: PublishDocumentation

on: 
  release:
    types: [published]

jobs:
  deploy_docs:
    runs-on: macos-latest
    steps:
    - uses: actions/checkout@v1
    - name: Publish Jazzy Docs
      uses: steven0351/publish-jazzy-docs@v1
      with:
        personal_access_token: ${{ secrets.ACCESS_TOKEN }}

Specify a Jazzy config file:

...
    - name: Publish Jazzy Docs
      uses: steven0351/publish-jazzy-docs@v1
      with:
        personal_access_token: ${{ secrets.ACCESS_TOKEN }}
        config: .jazzy.yml

Pass CLI args:

...
    - name: Publish Jazzy Docs
      uses: steven0351/publish-jazzy-docs@v1
      with:
        personal_access_token: ${{ secrets.ACCESS_TOKEN }}
        args: "--theme fullwidth --author Johnny Appleseed"

Specify a Jazzy version:

...
    - name: Publish Jazzy Docs
      uses: steven0351/publish-jazzy-docs@v1
      with:
        personal_access_token: ${{ secrets.ACCESS_TOKEN }}
        version: 0.11.2

Contributions

Pull requests are the preferred method of contributing. If you are unable to create a pull request, a detailed GitHub Issue describing the bug or feature request is more than welcome.