Skip to content

test spellcheck dict (#9) #10

test spellcheck dict (#9)

test spellcheck dict (#9) #10

Workflow file for this run

name: doc update check

Check failure on line 1 in .github/workflows/doc-update.yml

View workflow run for this annotation

GitHub Actions / .github/workflows/doc-update.yml

Invalid workflow file

(Line: 476, Col: 14): Unexpected value 'inherits'
# description: |
# This workflow is designed to help improve documentation quality.
#
# It proceeds with markdown linting and checks spelling in markdown files every time a markdown file is changed
# in a pull request.
#
# > NOTE: this workflow is only concerned with markdown documentation, not documentation in code (e.g. godoc).
#
# ## Usage of github action features
#
# * shared workflow
# * temporary token exchange using github app to elevate privileges within a trusted workflow
# * job summary (on actions UI)
#
# ## Limitations of github action features
#
# * [ ] did not find a way yet to retrieve the repo repo specified by the caller of this workflow.
# Had to resort to `master` to retrieve extra config files.
#
# ## TODO
#
# * [ ] to refactor repeated jobs as a matrix job? as separate workflow
# * [ ] should make an adapted version that runs on schedule and analyzes all markdown.
# * [ ] in this case, instead of commenting pull requests, it should raise issues.
# * [ ] should be able to retrieve config files and dictionary from the called ref, not master.
# * [ ] should be able to merge config files and dictionary with local definitions on target repo.
on:
workflow_call:
permissions:
pull-requests: write
contents: read
env:
artifacts_dir: artifacts
markdown_comment_title: Markdown linter
markdown_config: '.github/.markdownlint.yml'
markdown_artifact: markdown_comment.txt
spellcheck_comment_title: Markdown spelling check
spellcheck_config: .github/.spellcheck.yml
spellcheck_dict: .github/.wordlist.txt
spellcheck_artifact: spellcheck_comment.txt
jobs:
markdown-changed:
# description: |
# This triggers a markdown and spellcheck lint whenever documentation files change.
runs-on: ubuntu-latest
outputs:
proceed: ${{ steps.changed-markdown-files.outputs.any_changed }}
all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }}
steps:
- name: Originating repo checkout (e.g. public fork)
uses: actions/checkout@v5
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Get changed markdown files
uses: tj-actions/changed-files@v46
id: changed-markdown-files
with:
files: '**/*.md'
- name: Notify
run: |
echo "::notice::Detected some changed markdown files"
echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}"
markdown-lint:
needs: markdown-changed
if: ${{ needs.markdown-changed.outputs.proceed == 'true' }}
runs-on: ubuntu-latest
env:
lintreport: './markdownlint-report.txt'
outputs:
proceed: ${{ steps.report-exists.outputs.proceed }}
congrats: ${{ steps.congrats.outputs.proceed }}
report: ${{ steps.report-exists.outputs.report }}
steps:
- name: Originating repo checkout (e.g. public fork)
uses: actions/checkout@v5
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Checkout markdown config
uses: actions/checkout@v5
with:
repository: go-openapi/ci-workflows
ref: master # TODO: retrieve workflow ref
sparse-checkout: |
${{ env.markdown_config }}
sparse-checkout-cone-mode: false
path: ci-tools
- name: Copy markdown config
# TODO: merge with local if present
run: |
cp ci-tools/"${{ env.markdown_config}}" "${{ env.markdown_config }}"
- name: Run markdown linter
continue-on-error: true
id: markdownlint
uses: docker://avtodev/markdown-lint:v1.5
with:
config: ./${{ env.markdown_config }}
args: '${{ needs.markdown-changed.outputs.all_changed_files }}'
output: '${{ env.lintreport }}'
- name: Comment on success
if: ${{ steps.markdownlint.outcome == 'success' }}
id: congrats
run: |
echo "::notice:: no linting issue with changed markdown"
echo "proceed=true" >> $GITHUB_OUTPUT
- name: Comment on markdown lint complaining
if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }}
id: report-exists
run: |
echo 'report<<EOF' >> $GITHUB_OUTPUT
cat ${{ env.lintreport }}|sed -e '$a\' >> $GITHUB_OUTPUT
echo 'EOF' >> $GITHUB_OUTPUT
if [[ "$(cat ${{ env.lintreport }}|wc -l)" != "0" ]] ; then
echo "proceed=true" >> $GITHUB_OUTPUT
echo "::notice::Detected some linting issues with changed markdown"
cat ${{ env.lintreport }}|sed -e '$a\'
else
echo "proceed=false" >> $GITHUB_OUTPUT
echo "::notice::No linting issues with changed markdown"
fi
- name: Other linter errors
if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) == '' }}
run: |
echo "::error::markdown linter encountered an error"
exit 1
markdown-spelling:
needs: markdown-changed
if: ${{ needs.markdown-changed.outputs.proceed == 'true' }}
runs-on: ubuntu-latest
env:
spellcheckreport: './spellcheck-report.txt'
outputs:
proceed: ${{ steps.report-exists.outputs.proceed }}
congrats: ${{ steps.congrats.outputs.proceed }}
report: ${{ steps.report-exists.outputs.report }}
steps:
- uses: actions/checkout@v5
- name: Checkout spellcheck config
uses: actions/checkout@v5
with:
repository: go-openapi/ci-workflows
ref: master # TODO: retrieve workflow ref
sparse-checkout: |
${{ env.spellcheck_config }}
${{ env.spellcheck_dict }}
sparse-checkout-cone-mode: false
path: ci-tools
- name: Copy spellcheck config
# TODO: merge with local if present
run: |
cp ci-tools/${{ env.spellcheck_config }} ${{ env.spellcheck_config }}
cp ci-tools/${{ env.spellcheck_dict }} ${{ env.spellcheck_dict }}
- name: Spellcheck
uses: rojopolis/spellcheck-github-actions@0.51.0
continue-on-error: true
id: spellcheck
with:
config_path: ${{ env.spellcheck_config }}
source_files: '${{ needs.markdown-changed.outputs.all_changed_files }}'
task_name: markdown
output_file: ${{ env.spellcheckreport }}
- name: Comment on success
if: ${{ steps.spellcheck.outcome == 'success' }}
id: congrats
run: |
echo "::notice:: no spelling issue with changed markdown"
echo "proceed=true" >> $GITHUB_OUTPUT
echo "### Your changes to markdown docs show impeccable spelling. 👍" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "> ℹ️ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY
- name: Comment on spellcheck complaining
if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) != '' }}
id: report-exists
run: |
echo 'report<<EOF' >> $GITHUB_OUTPUT
cat ${{ env.spellcheckreport }}|sed -e '$a\' >> $GITHUB_OUTPUT
echo 'EOF' >> $GITHUB_OUTPUT
if [[ "$(cat ${{ env.spellcheckreport }}|wc -l)" != "0" ]] ; then
echo "proceed=true" >> $GITHUB_OUTPUT
echo "::notice::Detected some spelling issues with changed markdown"
cat ${{ env.lintreport }}|sed -e '$a\'
else
echo "proceed=false" >> $GITHUB_OUTPUT
echo "::notice::No spelling issues with changed markdown"
fi
- name: Other linter errors
if: ${{ steps.spellcheck.outcome != 'success' && hashFiles(env.spellcheckreport) == '' }}
run: |
echo "::error::spellcheck encountered an error"
exit 1
pr-markdown-congrats:
needs: markdown-lint
if: ${{ needs.markdown-lint.outputs.congrats == 'true' }}
runs-on: ubuntu-latest
outputs:
run_id: ${{ steps.notify_markdown_congrats.outputs.run_id }}
target_repo: ${{ steps.notify_markdown_congrats.outputs.target_repo }}
pr_number: ${{ steps.notify_markdown_congrats.outputs.pr_number }}
pr_sha: ${{ steps.notify_markdown_congrats.outputs.pr_sha }}
artifact_name: ${{ steps.notify_markdown_congrats.outputs.artifact_name }}
comment_title: ${{ steps.notify_markdown_congrats.outputs.comment_title }}
reactions: ${{ steps.notify_markdown_congrats.outputs.reactions }}
steps:
- name: Congrats
id: notify_markdown_congrats
run: |
mkdir -p "${{ env.artifacts_dir }}"
read -d '' MSG<<EOF
### ${{ env.markdown_comment_title }}
Markdown looks good to me. 👍
EOF
export MSG
printenv MSG > "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}"
echo "### Your changes to markdown docs look good. 👍" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "> ℹ️ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY
echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT"
echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT"
echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT"
echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT"
echo "reactions=hooray" >> "$GITHUB_OUTPUT"
- name: Upload comment as artifact
uses: actions/upload-artifact@v4
with:
path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }}
name: ${{ env.markdown_artifact }}
pr-comment-markdown-congrats:
name: Create or update congrats comment
needs: pr-markdown-congrats
uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref
secrets: inherit
with:
run_id: ${{ needs.pr-markdown-congrats.outputs.run_id }}
target_repo: ${{ needs.pr-markdown-congrats.outputs.target_repo }}
pr_number: ${{ needs.pr-markdown-congrats.outputs.pr_number }}
pr_sha: ${{ needs.pr-markdown-congrats.outputs.pr_sha }}
artifact_name: ${{ needs.pr-markdown-congrats.outputs.artifact_name }}
comment_title: ${{ needs.pr-markdown-congrats.outputs.comment_title }}
reactions: ${{ needs.pr-markdown-congrats.outputs.reactions }}
pr-markdown-report:
needs: markdown-lint
if: ${{ needs.markdown-lint.outputs.proceed == 'true' }}
outputs:
run_id: ${{ steps.notify_markdown_report.outputs.run_id }}
target_repo: ${{ steps.notify_markdown_report.outputs.target_repo }}
pr_number: ${{ steps.notify_markdown_report.outputs.pr_number }}
pr_sha: ${{ steps.notify_markdown_report.outputs.pr_sha }}
artifact_name: ${{ steps.notify_markdown_report.outputs.artifact_name }}
comment_title: ${{ steps.notify_markdown_report.outputs.comment_title }}
reactions: ${{ steps.notify_markdown_report.outputs.reactions }}
runs-on: ubuntu-latest
steps:
- name: Format PR comment
id: comment_formatter
uses: skills/action-text-variables@v3
with:
template-vars: >
{
"text": ${{ toJSON(needs.markdown-lint.outputs.report) }}
}
template-text: |
### ${{ env.markdown_comment_title }}
Some markdown linting issues were detected in the modified .md files. ⚠️
Perhaps they were already there before your changes.
This check is advisory only and not blocking. Please help us adopt a nice markdown style.
Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md).
<br>
{{ text }}
- name: Slap on the wrist
env:
OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}"
run: |
mkdir -p "${{ env.artifacts_dir }}"
printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.markdown_artifact }}"
echo "### Changed markdown docs need some formatting. ⚠️" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "> ℹ️ INFO: we use [avtodev/markdown-lint action](https://github.com/avto-dev/markdown-lint)" >> $GITHUB_STEP_SUMMARY
- name: Upload comment as artifact
uses: actions/upload-artifact@v4
with:
path: ${{ env.artifacts_dir }}/${{ env.markdown_artifact }}
name: ${{ env.markdown_artifact }}
- name: Notify
id: notify_markdown_report
run: |
echo "::notice::Commented pull request ${{ github.event.pull_request.number }}"
echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT"
echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT"
echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
echo "artifact_name=${{ env.markdown_artifact }}" >> "$GITHUB_OUTPUT"
echo "comment_title=${{ env.markdown_comment_title }}" >> "$GITHUB_OUTPUT"
echo "reactions=confused" >> "$GITHUB_OUTPUT"
pr-comment-markdown-report:
name: Create or update comment with report
needs: pr-markdown-report
uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref
secrets: inherit
with:
run_id: ${{ needs.pr-markdown-report.outputs.run_id }}
target_repo: ${{ needs.pr-markdown-report.outputs.target_repo }}
pr_number: ${{ needs.pr-markdown-report.outputs.pr_number }}
pr_sha: ${{ needs.pr-markdown-report.outputs.pr_sha }}
artifact_name: ${{ needs.pr-markdown-report.outputs.artifact_name }}
comment_title: ${{ needs.pr-markdown-report.outputs.comment_title }}
reactions: ${{ needs.pr-markdown-report.outputs.reactions }}
pr-markdown-spelling-congrats:
needs: markdown-spelling
if: ${{ needs.markdown-spelling.outputs.congrats == 'true' }}
outputs:
run_id: ${{ steps.notify_spelling_congrats.outputs.run_id }}
target_repo: ${{ steps.notify_spelling_congrats.outputs.target_repo }}
pr_number: ${{ steps.notify_spelling_congrats.outputs.pr_number }}
pr_sha: ${{ steps.notify_spelling_congrats.outputs.pr_sha }}
artifact_name: ${{ steps.notify_spelling_congrats.outputs.artifact_name }}
comment_title: ${{ steps.notify_spelling_congrats.outputs.comment_title }}
reactions: ${{ steps.notify_spelling_congrats.outputs.reactions }}
runs-on: ubuntu-latest
steps:
- name: Congrats
id: notify_spelling_congrats
run: |
mkdir -p artifacts
read -d '' MSG<<EOF
### ${{ env.spellcheck_comment_title }}
Spelling in mardown looks good to me. 👍
EOF
export MSG
printenv MSG > "${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }}"
echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT"
echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT"
echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT"
echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT"
echo "reactions=hooray" >> "$GITHUB_OUTPUT"
- name: Upload comment as artifact
uses: actions/upload-artifact@v4
with:
path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }}
name: ${{ env.spellcheck_artifact }}
pr-comment-spelling-congrats:
name: Create or update comment
needs: pr-markdown-spelling-congrats
uses: go-openapi/ci-workflows/.github/workflows/pr-comment.yml@master # <- TODO: caller's ref
secrets: inherit
with:
run_id: ${{ needs.pr-markdown-spelling-congrats.outputs.run_id }}
target_repo: ${{ needs.pr-markdown-spelling-congrats.outputs.target_repo }}
pr_number: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_number }}
pr_sha: ${{ needs.pr-markdown-spelling-congrats.outputs.pr_sha }}
artifact_name: ${{ needs.pr-markdown-spelling-congrats.outputs.artifact_name }}
comment_title: ${{ needs.pr-markdown-spelling-congrats.outputs.comment_title }}
reactions: ${{ needs.pr-markdown-spelling-congrats.outputs.reactions }}
pr-markdown-spelling-report:
needs: markdown-spelling
if: ${{ needs.markdown-spelling.outputs.proceed == 'true' }}
outputs:
run_id: ${{ steps.notify_spelling_report.outputs.run_id }}
target_repo: ${{ steps.notify_spelling_report.outputs.target_repo }}
pr_number: ${{ steps.notify_spelling_report.outputs.pr_number }}
pr_sha: ${{ steps.notify_spelling_report.outputs.pr_sha }}
artifact_name: ${{ steps.notify_spelling_report.outputs.artifact_name }}
comment_title: ${{ steps.notify_spelling_report.outputs.comment_title }}
reactions: ${{ steps.notify_spelling_report.outputs.reactions }}
runs-on: ubuntu-latest
steps:
- name: Format PR comment
id: comment_formatter
uses: skills/action-text-variables@v3
with:
template-vars: >
{
"text": ${{ toJSON(needs.markdown-spelling.outputs.report) }}
}
template-text: |
### ${{ env.spelling_comment_title }}
Some mispelled words were detected in the modified .md files. ⚠️
Perhaps they were already there before your changes.
This check is advisory only and not blocking. Please help us improve our documentation.
<br>
{{ text }}
- name: Slap on the wrist
env:
OUTPUT: "${{ steps.comment_formatter.outputs.updated-text }}"
run: |
mkdir -p "${{ env.artifacts_dir }}"
printenv OUTPUT > "${{ env.artifacts_dir}}/${{ env.spellcheck_artifact }}"
echo "### Changed markdown docs show some mispelled words. ⚠️" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "> ℹ️ INFO: we use [rojopolis/spellcheck-github-actions](https://github.com/rojopolis/spellcheck-github-actions)" >> $GITHUB_STEP_SUMMARY
- name: Upload comment as artifact
# description: |
# Calls a trusted shared workflow that temporarily elevates the caller's privileges
# to write a comment in the PR.
uses: actions/upload-artifact@v4
with:
path: ${{ env.artifacts_dir }}/${{ env.spellcheck_artifact }}
name: ${{ env.spellcheck_artifact }}
- name: Notify
id: notify_spelling_report
run: |
echo "::notice::Commented pull request ${{ github.event.pull_request.number }}"
echo "run_id=${{ github.run_id }}" >> "$GITHUB_OUTPUT"
echo "target_repo=${{ github.repository }}" >> "$GITHUB_OUTPUT"
echo "pr_number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
echo "pr_sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
echo "artifact_name=${{ env.spellcheck_artifact }}" >> "$GITHUB_OUTPUT"
echo "comment_title=${{ env.spellcheck_comment_title }}" >> "$GITHUB_OUTPUT"
echo "reactions=confused" >> "$GITHUB_OUTPUT"
pr-comment-spelling-report:
name: Create or update comment
needs: pr-markdown-spelling-report
secrets: inherits
uses: ./.github/workflows/pr-comment.yml
with:
run_id: ${{ needs.pr-markdown-spelling-report.outputs.run_id }}
target_repo: ${{ needs.pr-markdown-spelling-report.outputs.target_repo }}
pr_number: ${{ needs.pr-markdown-spelling-report.outputs.pr_number }}
pr_sha: ${{ needs.pr-markdown-spelling-report.outputs.pr_sha }}
artifact_name: ${{ needs.pr-markdown-spelling-report.outputs.artifact_name }}
comment_title: ${{ needs.pr-markdown-spelling-report.outputs.comment_title }}
reactions: ${{ needs.pr-markdown-spelling-report.outputs.reactions }}