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
        uses: actions/checkout@v4
      - 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 own dependencies
        run: python -m pip install -r src/nmdc_runtime/requirements.txt
      - name: Customize MkDocs configuration
        working-directory: _clones/microbiomedata/nmdc-runtime
        run: python ${{ github.workspace }}/src/nmdc_runtime/modify_mkdocs_config.py mkdocs.yml mkdocs.yml
      - name: Install dependencies of `nmdc-runtime` docs
        run: python -m pip install mkdocs-material mkdocs-mermaid2-plugin mkdocs-jupyter
        # Docs: https://www.mkdocs.org/user-guide/cli/
      - name: Compile source documents into HTML
        working-directory: _clones/microbiomedata/nmdc-runtime
        run: mkdocs build --site-dir ${{ 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: 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