Skip to content

Commit

Permalink
ci: Add markdownlint, test_converting_readme, and build_docs workflows
Browse files Browse the repository at this point in the history
- markdownlint runs against README.md to avoid any issues with
  converting it to HTML
- test_converting_readme converts README.md > HTML and uploads this test
  artifact to ensure that conversion works fine
- build_docs converts README.md > HTML and pushes the result to the
  docs branch to publish dosc to GitHub pages site.
- Fix markdown issues in README.md

Signed-off-by: Sergei Petrosian <[email protected]>
  • Loading branch information
spetrosi committed Aug 14, 2023
1 parent aff62c8 commit 5899d70
Show file tree
Hide file tree
Showing 8 changed files with 609 additions and 2 deletions.
1 change: 1 addition & 0 deletions .ansible-lint
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ skip_list:
exclude_paths:
- tests/roles/
- .github/
- .markdownlint.yaml
- examples/roles/
mock_modules:
- ini_file
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/ansible-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ jobs:
- name: Convert role to collection format
run: |
set -euxo pipefail
# Remove to avoid running ansible-test on unrelated file
rm -f .pandoc_template.html5
TOXENV=collection lsr_ci_runtox
# copy the ignore files
coll_dir=".tox/ansible_collections/$LSR_ROLE2COLL_NAMESPACE/$LSR_ROLE2COLL_NAME"
Expand Down
101 changes: 101 additions & 0 deletions .github/workflows/build_docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
# yamllint disable rule:line-length
name: Convert README.md to HTML and push to docs branch
on: # yamllint disable-line rule:truthy
push:
branches:
- main
paths:
- README.md
release:
types:
- published
permissions:
contents: read
jobs:
build_docs:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Update pip, git
run: |
set -euxo pipefail
sudo apt update
sudo apt install -y git
- name: Check out code
uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Ensure the docs branch
run: |
set -euxo pipefail
branch=docs
existed_in_remote=$(git ls-remote --heads origin $branch)
if [ -z "${existed_in_remote}" ]; then
echo "Creating $branch branch"
git config --global user.name "${{ github.actor }}"
git config --global user.email "${{ github.actor }}@users.noreply.github.com"
git checkout --orphan $branch
git reset --hard
git commit --allow-empty -m "Initializing $branch branch"
git push origin $branch
echo "Created $branch branch"
else
echo "Branch $branch already exists"
fi
- name: Checkout the docs branch
uses: actions/checkout@v3
with:
ref: docs

- name: Fetch README.md and .pandoc_template.html5 template from the workflow branch
uses: actions/checkout@v3
with:
sparse-checkout: |
README.md
.pandoc_template.html5
sparse-checkout-cone-mode: false
path: ref_branch
- name: Set RELEASE_VERSION based on whether run on release or on push
run: |
set -euxo pipefail
if [ ${{ github.event_name }} = release ]; then
echo "RELEASE_VERSION=${{ github.event.release.tag_name }}" >> $GITHUB_ENV
elif [ ${{ github.event_name }} = push ]; then
echo "RELEASE_VERSION=latest" >> $GITHUB_ENV
else
echo Unsupported event
exit 1
fi
- name: Ensure that version and docs directories exist
run: mkdir -p ${{ env.RELEASE_VERSION }} docs

- name: Convert README.md to HTML and save to the version directory
uses: docker://pandoc/core:latest
with:
args: >-
--from gfm --to html5 --toc --shift-heading-level-by=-1
--template ref_branch/.pandoc_template.html5
--output ${{ env.RELEASE_VERSION }}/README.html ref_branch/README.md
- name: Copy latest README.html to docs/index.html for GitHub pages
if: env.RELEASE_VERSION == 'latest'
run: cp ${{ env.RELEASE_VERSION }}/README.html docs/index.html

- name: Commit changes
run: |
git config --global user.name "${{ github.actor }}"
git config --global user.email "${{ github.actor }}@users.noreply.github.com"
git add ${{ env.RELEASE_VERSION }}/README.html docs/index.html
git commit -m "Update README.html for ${{ env.RELEASE_VERSION }}"
- name: Push changes
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: docs
34 changes: 34 additions & 0 deletions .github/workflows/markdownlint.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
# yamllint disable rule:line-length
name: Markdown Lint
on: # yamllint disable-line rule:truthy
pull_request:
merge_group:
branches:
- main
types:
- checks_requested
push:
branches:
- main
workflow_dispatch:
permissions:
contents: read
jobs:
markdownlint:
runs-on: ubuntu-latest
steps:
- name: Update pip, git
run: |
set -euxo pipefail
sudo apt update
sudo apt install -y git
- name: Check out code
uses: actions/checkout@v3

- name: Lint README.md
uses: docker://avtodev/markdown-lint:master
with:
args: README.md
config: .markdownlint.yaml
43 changes: 43 additions & 0 deletions .github/workflows/test_converting_readme.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
# yamllint disable rule:line-length
name: Test converting README.md to README.html
on: # yamllint disable-line rule:truthy
pull_request:
merge_group:
branches:
- main
types:
- checks_requested
push:
branches:
- main
permissions:
contents: read
jobs:
test_converting_readme:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Update pip, git
run: |
set -euxo pipefail
sudo apt update
sudo apt install -y git
- name: Check out code
uses: actions/checkout@v3

- name: Convert README.md to HTML and save to the version directory
uses: docker://pandoc/core:latest
with:
args: >-
--from gfm --to html5 --toc --shift-heading-level-by=-1
--template .pandoc_template.html5
--output README.html README.md
- name: Upload README.html as an artifact
uses: actions/upload-artifact@master
with:
name: README.html
path: README.html
Loading

0 comments on commit 5899d70

Please sign in to comment.