Initial (#1)

.github/FUNDING.yml

@@ -0,0 +1 @@
+open_collective: ponyc

.github/linters/.markdown-lint.yml

@@ -0,0 +1,3 @@
+{
+  "MD013": false
+}

.github/workflows/add-discuss-during-sync.yml

@@ -0,0 +1,29 @@
+name: Add discuss during sync label
+
+on:
+  issues:
+    types:
+      - opened
+      - reopened
+  issue_comment:
+    types:
+      - created
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - ready_for_review
+      - reopened
+  pull_request_review:
+    types:
+      - submitted
+
+jobs:
+  add-label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Add "discuss during sync" label to active GH entity
+        uses: andymckay/labeler@467347716a3bdbca7f277cb6cd5fa9c5205c5412
+        with:
+          repo-token: ${{ secrets.PONYLANG_MAIN_API_TOKEN }}
+          add-labels: "discuss during sync"

.github/workflows/pr.yml

@@ -0,0 +1,64 @@
+name: PR
+
+on: pull_request
+
+jobs:
+  lint-entrypoint-py:
+    name: Lint entrypoint.py
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: pylint
+        run: make pylint
+
+  superlinter:
+    name: Lint bash, docker, markdown, and yaml
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Lint codebase
+        uses: docker://github/super-linter:v3.8.3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VALIDATE_ALL_CODEBASE: true
+          VALIDATE_BASH: true
+          VALIDATE_DOCKERFILE: true
+          VALIDATE_MD: true
+          VALIDATE_YAML: true
+
+  validate-public-release-image-builds:
+    name: Validate public release image builds
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Docker build
+        run: make build-release config=public
+
+  validate-public-latest-image-builds:
+    name: Validate public latest image builds
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Docker build
+        run: make build-latest config=public
+
+  validate-private-release-image-builds:
+    name: Validate private release image builds
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Docker build
+        run: make build-release config=private
+        env:
+          MATERIAL_INSIDERS_ACCESS: ${{ secrets.MATERIAL_INSIDERS_ACCESS }}
+
+  validate-private-latest-image-builds:
+    name: Validate private latest image builds
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Docker build
+        run: make build-latest config=private
+        env:
+          MATERIAL_INSIDERS_ACCESS: ${{ secrets.MATERIAL_INSIDERS_ACCESS }}
+

.github/workflows/remove-discuss-during-sync.yml

@@ -0,0 +1,19 @@
+name: Remove discuss during sync label
+
+on:
+  issues:
+    types:
+      - closed
+  pull_request_target:
+    types:
+      - closed
+
+jobs:
+  remove-label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Remove label
+        uses: andymckay/labeler@467347716a3bdbca7f277cb6cd5fa9c5205c5412
+        with:
+          repo-token: ${{ secrets.PONYLANG_MAIN_API_TOKEN }}
+          remove-labels: "discuss during sync"

.github/workflows/update-latest-image.yml

@@ -0,0 +1,69 @@
+name: Update latest images
+
+on:
+  repository_dispatch:
+    types:
+      - ponyc-musl-nightly-released
+  workflow_dispatch:
+
+concurrency:
+  group: "rebuild-latest-images"
+  cancel-in-progress: true
+
+jobs:
+  rebuild-public-latest-image:
+    name: Rebuild latest public image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v3
+      - name: Login to Docker Hub
+        run: "docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD"
+        env:
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+      - name: Build
+        run: make build-latest config=public
+      - name: Push
+        run: make push-latest config=public
+      - name: Send alert on failure
+        if: ${{ failure() }}
+        uses: zulip/github-actions-zulip@35d7ad8e98444f894dcfe1d4e17332581d28ebeb
+        with:
+          api-key: ${{ secrets.ZULIP_SCHEDULED_JOB_FAILURE_API_KEY }}
+          email: ${{ secrets.ZULIP_SCHEDULED_JOB_FAILURE_EMAIL }}
+          organization-url: 'https://ponylang.zulipchat.com/'
+          to: notifications
+          type: stream
+          topic: ${{ github.repository }} scheduled job failure
+          content: ${{ github.server_url}}/${{ github.repository }}/actions/runs/${{ github.run_id }} failed.
+
+  rebuild-private-latest-image:
+    name: Rebuild latest private image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v3
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v1
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build
+        run: make build-latest config=private
+        env:
+          MATERIAL_INSIDERS_ACCESS: ${{ secrets.MATERIAL_INSIDERS_ACCESS }}
+      - name: Push
+        run: make push-latest config=private
+      - name: Send alert on failure
+        if: ${{ failure() }}
+        uses: zulip/github-actions-zulip@35d7ad8e98444f894dcfe1d4e17332581d28ebeb
+        with:
+          api-key: ${{ secrets.ZULIP_SCHEDULED_JOB_FAILURE_API_KEY }}
+          email: ${{ secrets.ZULIP_SCHEDULED_JOB_FAILURE_EMAIL }}
+          organization-url: 'https://ponylang.zulipchat.com/'
+          to: notifications
+          type: stream
+          topic: ${{ github.repository }} scheduled job failure
+          content: ${{ github.server_url}}/${{ github.repository }}/actions/runs/${{ github.run_id }} failed.

.markdownlintignore

@@ -0,0 +1,3 @@
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+.release-notes/

Dockerfile

@@ -0,0 +1,28 @@
+ARG FROM_TAG=release-alpine
+FROM ponylang/ponyc:${FROM_TAG}
+
+ARG PACKAGE
+
+RUN apk add --update --no-cache \
+  bash \
+  libffi \
+  libffi-dev \
+  libressl \
+  libressl-dev \
+  make \
+  python3 \
+  python3-dev \
+  py3-pip \
+  tar
+
+RUN pip3 install --upgrade pip \
+  gitpython \
+  in_place \
+  mkdocs \
+  ${PACKAGE} \
+  pylint \
+  pyyaml
+
+COPY entrypoint.py /entrypoint.py
+
+ENTRYPOINT ["/entrypoint.py"]

LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2022, The Pony Developers
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -0,0 +1,40 @@
+config ?= public
+
+ifdef config
+	ifeq (,$(filter $(config),public private))
+		$(error Unknown configuration "$(config)")
+	endif
+endif
+
+ifeq ($(config),private)
+	IMAGE := ghcr.io/ponylang/library-documentation-action-v2
+	PACKAGE = "git+https://${MATERIAL_INSIDERS_ACCESS}@github.com/squidfunk/mkdocs-material-insiders.git"
+else
+	IMAGE = ponylang/library-documentation-action-v2
+	PACKAGE = "mkdocs-material"
+endif
+
+all: pylint
+
+build:
+	docker build --pull --build-arg PACKAGE="${PACKAGE}" --build-arg FROM_TAG="${version}-alpine" -t "${IMAGE}:${version}" .
+
+build-latest:
+	docker build --pull --build-arg PACKAGE="${PACKAGE}" --build-arg FROM_TAG="alpine" -t "${IMAGE}:latest" .
+
+build-release:
+	docker build --pull --build-arg PACKAGE="${PACKAGE}" --build-arg FROM_TAG="release-alpine" -t "${IMAGE}:release" .
+
+push: build
+	docker push "${IMAGE}:${version}"
+
+push-latest: build-latest
+	docker push "${IMAGE}:latest"
+
+push-release: build-release
+	docker push "${IMAGE}:release"
+
+pylint: build-latest
+	docker run --entrypoint pylint --rm "${IMAGE}:latest" /entrypoint.py
+
+.PHONY: build pylint

README.md

@@ -1,2 +1,103 @@
 # library-documentation-action-v2
-Generates documentation for Pony libraries
+
+A GitHub Action that generates documentation for a Pony library and updates that documentation on GitHub pages. The library in question must have a Makefile with a target `docs` that can be used to generate the documentation that can be feed to `mkdocs`.
+
+Generated docs can be uploaded for hosting anywhere you like. The examples below show them being hosted on GitHub pages.
+
+You need to supply the url of your site to the action in the `site_url` option. For GitHub pages, that domain will be `https://USER_OR_ORG_NAME.github.io/REPOSITORY_NAME/`.
+
+## Example workflow
+
+In **release.yaml**, in addition the usual [release-bot-action](https://github.com/ponylang/release-bot-action) workflow entries.
+
+```yml
+name: Release
+
+on:
+  push:
+    tags:
+      - \d+.\d+.\d+
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "update-documentation"
+  cancel-in-progress: true
+
+jobs:
+  generate-documentation:
+    name: Generate documentation for release
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Generate documentation
+        uses: ponylang/library-documentation-action@via-github-action
+        with:
+          site_url: "https://MYORG.github.io/MYLIBRARY/"
+          library_name: "MYLIBRARY"
+          docs_build_dir: "build/MY-LIBRARY-docs"
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'build/MY-LIBRARY-docs/site/'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+```
+
+## Manually triggering a documentation build and deploy
+
+GitHub has a [`workflow_dispatch`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) event that provides a button the actions UI to trigger the workflow. You can set up a workflow to respond to a workflow_dispatch if you need to regenerate documentation from the last commit on a given branch without doing a full release.
+
+We suggest that you install the a `workflow_dispatch` driven workflow to generate documentation the when you first install this action so you don't need to do a superfluous release.
+
+```yml
+name: Manually generate documentation
+
+on:
+  workflow_dispatch
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "update-documentation"
+  cancel-in-progress: true
+
+jobs:
+  generate-documentation:
+    name: Generate documentation for release
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Generate documentation
+        uses: ponylang/library-documentation-action@via-github-action
+        with:
+          site_url: "https://MYORG.github.io/MYLIBRARY/"
+          library_name: "MYLIBRARY"
+          docs_build_dir: "build/MY-LIBRARY-docs"
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'build/MY-LIBRARY-docs/site/'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+```