combine yaml files using paths-filter to determine order

.github/workflows/generate_help_and_readme.yaml

@@ -0,0 +1,116 @@
+name: Generate help docs and README
+
+jobs:
+  check-paths:
+    runs-on: ubuntu-latest
+    outputs:
+      parsing-changed: ${{ steps.filter.outputs.parsing }}
+      docs-changed: ${{ steps.filter.outputs.docs }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            parsing:
+              - 'src/sim_recon/cli/parsing/*'
+              - 'src/sim_recon/settings/formatting.py'
+            docs:
+              - 'docs/**/*'
+  generate-help-docs:
+    runs-on: ubuntu-latest
+    needs: check-paths
+    if: needs.check-paths.outputs.parsing-changed == 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+      - name: Copy template
+        run: cp -f docs/template.md README.md
+      - name: Install (without dependencies)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . --no-deps
+      - name: Ensure README exists
+        run: |
+          if [ ! -f "README.md" ]; then
+            touch README.md
+          fi
+      - name: Get help strings from package
+        run: |
+          python -m sim_recon.cli.parsing.otf '--help' >docs/help/sim_otf.txt
+          python -m sim_recon.cli.parsing.recon '--help' >docs/help/sim_recon.txt
+          python -m sim_recon.cli.parsing.otf_view '--help' >docs/help/otf_view.txt
+      - name: Setup git
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+      - name: Push help docs changes (if any)
+        run: |
+          if git update-index --refresh && git diff-index --quiet HEAD --; then
+            git add docs/help/*
+            git commit -m "Automated update of help docs"
+
+            branch_name="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}"
+            git push -u origin HEAD:$branch_name
+          fi
+
+  make-README:
+    needs: [check-paths, generate-help-docs]
+    runs-on: ubuntu-latest
+    # Putting generate-help-docs in "needs" requires it to wait
+    # always() && !cancelled() means it will run regardless or the result of
+    # the needs, unless the job is cancelled, which is necessary as a failure
+    # of a need will otherwise cause a job to not run.
+    # This job will run if:
+    # - generate-help-docs completes successfully
+    # - the docs-changed filter returns 'true'
+    if: needs.generate-help-docs.result == "success" || always() && !cancelled() && needs.check-paths.outputs.docs-changed == 'true'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            docs:
+              - 'docs/**/*'
+      - name: Fill template
+        working-directory: "docs/"
+        timeout-minutes: 0.1
+        run: |
+          sub_doc_parts_from() {
+            template="$1"
+            directory="$2"
+
+            for file in "$directory"/*; do
+                if [ -f "$file" ]; then
+                    placeholder="{{ $(echo "${file^^}" | tr ./ _) }}"
+                    echo "Saving $file to $placeholder with expanded environment variables" >&2
+                    # Export file contents to text following a pattern in template.md, e.g.:
+                    # section/test_file.md would replace "{{ SECTION_TEST_FILE_MD }}""
+                    template="${template//"$placeholder"/"$(<"$file")"}"
+                fi
+            done
+            echo "$template"
+          }
+          # Fills from docs/sections sections, then docs/help (note "working-directory")
+          sub_doc_parts_from "$(sub_doc_parts_from "$(<template.md)" "sections")" "help">../README.md
+      - name: Setup git
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+      - name: Push README.md changes (if any)
+        run: |
+          if git update-index --refresh && git diff-index --quiet HEAD --; then
+            git add README.md
+            git commit -m "Automated update of README.md from docs"
+
+            branch_name="${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}"
+            git push -u origin origin HEAD:$branch_name
+          fi