fetch-and-compile-nmdc-runtime-documentation.yml

name: Fetch and compile NMDC Runtime 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 from `nmdc-runtime/main`
        uses: actions/checkout@v4
        with:
          # Notes:
          # - `repository` format is: "{owner_name}/{repo_name}"
          # - `sparse-checkout` lists the same files as the `mkdocs.yml` GHA workflow in `nmdc-runtime`
          repository: microbiomedata/nmdc-runtime  # format is "{owner_name}/{repo_name}"
          ref: main
          sparse-checkout: |
            docs
            mkdocs_overrides
            mkdocs.yml
          path: _clones/microbiomedata/nmdc-runtime  # where, locally, to create the clone
        # Docs: https://github.com/actions/setup-python
      - name: Set up Python
        uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - name: Install dependencies of `nmdc-runtime` docs
        run: | 
          python -m pip install \
            mkdocs-material \
            mkdocs-mermaid2-plugin \
            mkdocs-jupyter \
            pymdown-extensions
        # Docs: https://www.mkdocs.org/user-guide/cli/
        # Docs: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
        # TODO: Make the `site_url` configurable (e.g. via an environment variable).
      - name: Compile source documents into HTML
        working-directory: _clones/microbiomedata/nmdc-runtime
        run: |
          echo '{
            "INHERIT": "mkdocs.yml",
            "site_dir": "${{ github.workspace }}/_dist",
            "site_url": "https://microbiomedata.github.io/docs/runtime/"
          }' | mkdocs build -f -
        # 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: nmdc-runtime-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