Feature 534495: Documentation Generation (GH Pages) #17
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Test Documentation Generation | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| branch_type: | |
| description: 'Type of branch to simulate' | |
| required: true | |
| default: 'main' | |
| type: choice | |
| options: | |
| - main | |
| - release/v1 | |
| - release/v2 | |
| pull_request: | |
| branches: | |
| - main | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| jobs: | |
| test-docs-generation: | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages-test | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Check out code | |
| uses: actions/checkout@v4 | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version-file: .nvmrc | |
| - name: Setup Ruby | |
| uses: ruby/setup-ruby@v1 | |
| with: | |
| ruby-version: '3.2' | |
| bundler-cache: true | |
| - name: Install dependencies | |
| run: npm ci | |
| - name: Set branch type based on trigger | |
| id: set-branch | |
| run: | | |
| if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then | |
| echo "BRANCH_TYPE=${{ github.event.inputs.branch_type }}" >> $GITHUB_ENV | |
| else | |
| echo "BRANCH_TYPE=main" >> $GITHUB_ENV | |
| fi | |
| echo "VERSION=1.2.3" >> $GITHUB_ENV | |
| - name: Generate documentation | |
| run: | | |
| mkdir -p .github/scripts/docs | |
| bash .github/scripts/docs/generate-and-publish-docs.sh "$BRANCH_TYPE" "$VERSION" | |
| - name: Build Jekyll site | |
| run: | | |
| # Create Jekyll source directory | |
| mkdir -p site-src | |
| # Copy all docs except INDEX.md (we'll handle that separately) | |
| cp -r docs/* site-src/ | |
| # Process INDEX.md - replace .md with .html and add proper front matter | |
| sed 's/\.md/\.html/g' docs/INDEX.md > site-src/index.md | |
| # Make sure front matter is formatted correctly (with empty line after) | |
| sed -i '1s/^/---\nlayout: default\ntitle: DXT Documentation\n---\n\n/' site-src/index.md | |
| # Process all other markdown files to fix links | |
| find site-src -name "*.md" | while read file; do | |
| sed -i 's/\.md/\.html/g' "$file" | |
| done | |
| # Create Gemfile with exact dependencies | |
| cat > site-src/Gemfile << EOF | |
| source 'https://rubygems.org' | |
| gem 'jekyll', '~> 4.4.0' | |
| gem 'jekyll-remote-theme', '0.4.3' | |
| gem 'jekyll-relative-links' | |
| gem 'jekyll-sass-converter', '~> 3.0.0' | |
| gem 'jekyll-seo-tag' | |
| gem 'webrick' # required for Ruby 3.x | |
| EOF | |
| # Write Jekyll _config.yml with proper configuration | |
| cat > site-src/_config.yml << EOF | |
| title: DXT Documentation | |
| description: Documentation for the DEFRA Forms Engine Plugin | |
| markdown: kramdown | |
| kramdown: | |
| input: GFM | |
| syntax_highlighter: rouge | |
| # Use remote GitHub-hosted theme | |
| remote_theme: pages-themes/minimal@v0.2.0 | |
| plugins: | |
| - jekyll-remote-theme | |
| - jekyll-relative-links | |
| - jekyll-seo-tag | |
| relative_links: | |
| enabled: true | |
| collections: true | |
| defaults: | |
| - scope: | |
| path: "schemas" | |
| type: "pages" | |
| values: | |
| layout: default | |
| - scope: | |
| path: "features" | |
| type: "pages" | |
| values: | |
| layout: default | |
| - scope: | |
| path: "" | |
| type: "pages" | |
| values: | |
| layout: default | |
| EOF | |
| # Install dependencies using Bundler | |
| cd site-src | |
| bundle install | |
| # Build the site using Jekyll with bundler | |
| bundle exec jekyll build --destination ../_site | |
| cd .. | |
| # Display final build structure for debugging | |
| echo "Final site structure:" | |
| find _site -type f | grep -v ".git" | grep -e "index.html" -e "assets" -e "schema" | head -n 10 | |
| echo "... (and more files)" | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v5 | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: '_site' | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 | |
| with: | |
| timeout: 600000 # 10 minutes in milliseconds |