fetch-and-compile-workflow-documentation.yml

name: Fetch and compile workflow documentation

on:
  push: { branches: [ main ] }
  workflow_dispatch: { }
  # Allow this workflow to be called by other workflows.
  # Reference: https://docs.github.com/en/actions/using-workflows/reusing-workflows
  workflow_call: { }

jobs:
  compile:
    name: Compile
    runs-on: ubuntu-latest
    steps:
        # Docs: https://github.com/actions/checkout
      - name: Check out commit
        uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - name: Install dependencies of workflow documentation
        run: python -m pip install sphinx sphinx_rtd_theme pillow
        # Note: This shell script will store the chapters under `/tmp/book/src/`.
        #
        # Note: The source files for the overview chapter and Chapter 1 reside
        #       in this `docs` repo. We will process those in a subsequent step.
        #
      - name: Fetch documentation sources and arrange into chapters
        run: |
          chmod +x ./pullers/workflow_docs/fetch_docs_sources.sh
          ./pullers/workflow_docs/fetch_docs_sources.sh
      - name: Introduce additional source files, static files, and a configuration file
        run: |
          cp -r pullers/workflow_docs/metagenome_workflow_overview/docs /tmp/book/src/chapters/1_Metagenome_Workflow_Overview
          cp -r pullers/workflow_docs/_static                           /tmp/book/src/_static          
          cp    pullers/workflow_docs/overview.rst                      /tmp/book/src/chapters/overview.rst
          cp    pullers/workflow_docs/index.rst                         /tmp/book/src/index.rst
          cp    pullers/workflow_docs/conf.py                           /tmp/book/src/conf.py
      - name: Compile source documents into HTML
        run: sphinx-build --builder html /tmp/book/src ${{ github.workspace }}/_dist
        # Upload the result as an "artifact" so it can then be downloaded and used by another job.
      - name: Save the HTML for publishing later  # Docs: https://github.com/actions/upload-artifact
        uses: actions/upload-artifact@v4
        with:
          name: workflow-documentation-as-html
          # Note: Relative `path` values here are relative to the _workspace_, not to the current working directory.
          #       Reference: https://github.com/actions/upload-artifact/pull/477#issue-2044900649
          path: _dist
          if-no-files-found: error
          retention-days: 1  # Note: 1 day is the shortest period possible