Skip to content

GitHub Action to generate and publish documentation #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rnc merged 2 commits into from
May 2, 2025
Merged

GitHub Action to generate and publish documentation #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0ca858
GitHub Action to generate and publish documentation
jmtd Feb 27, 2024
15d440e
gendocs.sh: generate links to source files on GitHub
jmtd May 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions .github/workflows/static.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
# Runs on pushes targeting the default branch
push:
branches:
- "v1"
- "gh-pages-doc-steps"

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false

jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Install Behave and related
run: |
pip3 install behave docker lxml markdown
- name: Generate documentation
run: |
mkdir -p pages
./tools/gendocs.sh > pages/index.html
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: 'pages'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
38 changes: 38 additions & 0 deletions tools/gendocs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
#!/bin/bash
set -euo pipefail

# we expect to be run from the root of the behave-test-steps repository
test -d steps

# necessary to stop behave quitting early
mkdir -p features
touch features/blank.feature

cat <<EOF
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<title>behave-test-steps steps documentation</title>
</head>
<body>
<header>
<h1>behave-test-steps steps documentation</h1>
</header>
EOF

fork="cekit" # TODO: permit override from environment
branch="v1"
linkroot="https://github.com/${fork}/behave-test-steps/blob/${branch}/"

behave --dry-run --format=steps.catalog --no-summary |
sed -E 's!^((Given|When|Then).*)$!## \1\n!' | # turn steps into Mdwn headers
sed -E "s#Location: (.*):(.*)#[\1:\2](${linkroot}\1\#L\2)\n#" | # mdwn-link to the implementation
sed -E 's#^ ##' | # stop preformatted descriptions # convert to HTML
python3 -m markdown # convert to HTML

cat <<EOF

</body>
</html>
EOF