GitHub Action to Publish Documentation

[osxhacker]

Creating a CircleCI job which automatically updates the github documentation whenever a new version is published could help those unfamiliar with the project release flow know what version to use.

[osxhacker]

Hi @adrobisch ,

Pinging you in the event this issue went unnoticed since the latest version of scraml is v0.13.1 and the docs currently are for v0.11.6.

[adrobisch]

Thanks for the ping, yes I missed this one 🤦. I think an additional Github Action step would be easier to integrate with the current release flow. Is adding that something you would be interested in? I will do a manual update asap.

[osxhacker]

Thanks for the ping, yes I missed this one

No worries, this isn't the highest priority kind of thing IMHO 😄 .

I think an additional Github Action step would be easier to integrate with the current release flow. Is adding that something you would be interested in?

Agreed. Doing automatic docs updates via a Github Action is a better solution. I believe creating one would require admin permissions for the repository, though, and I no longer have that access. What I could do is the research and then update this ticket with what I believe the Action definition could be.

[osxhacker]

Hi @adrobisch ,

Here is an example Github Action which uses sbt to publish a paradox-based site. I tested this in Scala BSON Query a few minutes ago and it worked as desired.

# Publish paradox-based documentation to the gh-pages branch when 'main' is
# updated.

name: Scala gh-pages CI
on:
  push:
    branches: [ "main" ]

  # Allow running this workflow manually from the Actions tab.
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up JDK 11
      uses: actions/setup-java@v3
      with:
        java-version: '11'
        distribution: 'temurin'
        cache: 'sbt'
    - name: Build Paradox documentation
      run: JAVA_OPTS="--add-opens java.base/java.lang=ALL-UNNAMED" sbt paradox
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v1
      with:
        path: "./target/paradox/site/main"

  # Deploy job
  deploy:
    # Add a dependency to the build job
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    # Specify runner + deployment step
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

[adrobisch]

👌 thanks a lot for the example! Looking into how to adapt it for use with sbt-github-actions.
The permissions part is already very valuable info.

[osxhacker]

Closing this issue as it is addressed in PR #52 .