From c0ca85879afb436b103c456026c9b1bf3d8704ee Mon Sep 17 00:00:00 2001 From: Jonathan Dowland Date: Tue, 27 Feb 2024 16:17:53 +0000 Subject: [PATCH 1/2] GitHub Action to generate and publish documentation This generates a basic list of Steps that are made available by this library and publishes it to GitHub pages. Signed-off-by: Jonathan Dowland --- .github/workflows/static.yml | 51 ++++++++++++++++++++++++++++++++++++ tools/gendocs.sh | 34 ++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 .github/workflows/static.yml create mode 100755 tools/gendocs.sh diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml new file mode 100644 index 0000000..632c69e --- /dev/null +++ b/.github/workflows/static.yml @@ -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 diff --git a/tools/gendocs.sh b/tools/gendocs.sh new file mode 100755 index 0000000..4cf4ed6 --- /dev/null +++ b/tools/gendocs.sh @@ -0,0 +1,34 @@ +#!/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 < + + + + behave-test-steps steps documentation + + +
+

behave-test-steps steps documentation

+
+EOF + +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](\1)\n#' | # mdwn-link to implementation + sed -E 's#^ ##' | # stop preformatted descriptions + python3 -m markdown + +cat < + +EOF From 15d440ecb6e3ca5d02551d01be476e2de24f4fcc Mon Sep 17 00:00:00 2001 From: Jonathan Dowland Date: Fri, 2 May 2025 13:43:12 +0100 Subject: [PATCH 2/2] gendocs.sh: generate links to source files on GitHub Signed-off-by: Jonathan Dowland --- tools/gendocs.sh | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/tools/gendocs.sh b/tools/gendocs.sh index 4cf4ed6..e4b129f 100755 --- a/tools/gendocs.sh +++ b/tools/gendocs.sh @@ -21,11 +21,15 @@ cat < EOF -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](\1)\n#' | # mdwn-link to implementation - sed -E 's#^ ##' | # stop preformatted descriptions - python3 -m markdown +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 <