Merge pull request #18 from microbiomedata/3-prototype-pulling-in-wor…

…kflow-documentation-directly-from-a-source-repo

Incorporate MAG Workflow documentation into GitHub Pages site

.github/workflows/deploy-to-gh-pages.yml

@@ -23,6 +23,9 @@ jobs:
   fetch-and-compile-nmdc-runtime-documentation:
     name: Fetch and compile NMDC Runtime documentation
     uses: ./.github/workflows/fetch-and-compile-nmdc-runtime-documentation.yml
+  fetch-and-compile-mag-workflow-documentation:
+    name: Fetch and compile MAG workflow documentation
+    uses: ./.github/workflows/fetch-and-compile-mag-workflow-documentation.yml
 
   build:
     name: Compile main website
@@ -32,6 +35,7 @@ jobs:
       - compile-legacy-nmdc-documentation
       - compile-legacy-workflow-documentation
       - fetch-and-compile-nmdc-runtime-documentation
+      - fetch-and-compile-mag-workflow-documentation
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -45,10 +49,11 @@ jobs:
       - name: Assemble website file tree
         run: |
           ls -R artifacts
-          mkdir -p _build/html _build/html/legacy
+          mkdir -p _build/html _build/html/legacy _build/html/workflows
           cp -R artifacts/legacy-nmdc-documentation-as-html _build/html/legacy/nmdc-documentation
           cp -R artifacts/legacy-workflow-documentation-as-html _build/html/legacy/workflow-documentation
           cp -R artifacts/nmdc-runtime-documentation-as-html _build/html/nmdc-runtime-documentation
+          cp -R artifacts/mag-workflow-documentation-as-html _build/html/workflows/mag-workflow-documentation
           cp content/index.html _build/html/index.html
       - name: Save the result for publishing to GitHub Pages  # Docs: https://github.com/actions/upload-pages-artifact
         uses: actions/upload-pages-artifact@v3

.github/workflows/fetch-and-compile-mag-workflow-documentation.yml

@@ -0,0 +1,48 @@
+name: Fetch and compile MAG 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: Check out commit from `metaMAGs/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/metaMAGs  # format is "{owner_name}/{repo_name}"
+          ref: main
+          sparse-checkout: |
+            docs
+          path: _clones/microbiomedata/metaMAGs  # 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 `metaMAGs` docs
+        run: python -m pip install sphinx
+        # Docs: https://www.mkdocs.org/user-guide/cli/
+      - name: Compile source documents into HTML
+        working-directory: _clones/microbiomedata/metaMAGs
+        run: sphinx-build -b html docs ${{ 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: mag-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