Merge pull request #2 from microbiomedata/1-docs-update-gha-workflow-…

…to-fetch-and-compile-the-raw-nmdc-runtime-documentation

Configure GitHub Actions to fetch and compile Runtime docs (WIP)

.github/workflows/fetch-and-compile-nmdc-runtime-documentation.yml

@@ -0,0 +1,53 @@
+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-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
+          path: ${{ github.workspace }}/_dist
+          if-no-files-found: error
+          retention-days: 1  # Note: 1 day is the shortest period possible

src/.gitignore

@@ -0,0 +1,2 @@
+# Ignore all the `.venv` directories in the child directories of the current directory.
+/*/.venv

src/nmdc_runtime/modify_mkdocs_config.py

@@ -0,0 +1,76 @@
+# This script modifies a copy of the `mkdocs.yml` configuration file residing in the `nmdc-runtime` repository.
+
+from typing import List
+import argparse
+import re
+from io import StringIO
+
+import yaml
+
+# TODO: Write some tests that target this code.
+
+# This is the value you want the `site_url` YAML field to contain.
+SITE_URL = r"https://microbiomedata.github.io/docs/nmdc-runtime"
+
+
+def sanitize_yaml_lines(raw_lines: List[str]):
+    r"""Helper function that wraps a specific value in quotes so PyYAML can parse it."""
+
+    sanitized_lines = []
+    for line in raw_lines:
+        matches = re.match(
+            r"^(\s*)(format):\s*(!!python/name:pymdownx\.superfences\.fence_code_format)\s*$",
+            line,
+        )
+        if matches is not None:
+            spaces = matches[1]
+            label = matches[2]
+            value = matches[3]
+            sanitized_line = f'{spaces}{label}: "{value}"'
+        else:
+            sanitized_line = line
+        sanitized_lines.append(sanitized_line)
+    return sanitized_lines
+
+
+def main():
+    r"""
+    Modifies a MkDocs configuration file so it can be used to build a website that will be hosted at a different URL
+    from the URL the file currently lists.
+    """
+
+    parser = argparse.ArgumentParser(
+        description="Modify the `mkdocs.yml` file from `nmdc-runtime`"
+    )
+    parser.add_argument(
+        "input_file_path", type=argparse.FileType("r"), help="Path to `mkdocs.yml` file"
+    )
+    parser.add_argument(
+        "output_file_path", type=argparse.FileType("w"), help="Path to output file"
+    )
+    args = parser.parse_args()
+
+    # Read the input file, parsing its contents as YAML.
+    print(f"Parsing original YAML file: {args.input_file_path.name}")
+    with open(args.input_file_path.name, "r") as f:
+        # Note: When I used `safe_load()` or I used `load()` with `Loader=yaml.SafeLoader`, Python raised this error:
+        #       ```
+        #       yaml.constructor.ConstructorError: could not determine a constructor for the tag
+        #       'tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format'
+        #       ```
+        #       So, I first modify the relevant line of the YAML file, putting quotes around its value,
+        #       since PyYAML seems to load the result OK.
+        #
+        raw_lines = f.readlines()
+        sanitized_lines = sanitize_yaml_lines(raw_lines)
+        stream = StringIO("\n".join(sanitized_lines))
+        mkdocs_config: dict = yaml.safe_load(stream)
+
+    # Replace the `site_url` value.
+    # TODO: Make the value configurable (e.g. via a script argument or environment variable).
+    print("Replacing site-specific values.")
+    mkdocs_config["site_url"] = SITE_URL
+
+    print(f"Writing resulting YAML file: {args.output_file_path.name}")
+    with open(args.output_file_path.name, "w") as f:
+        yaml.safe_dump(mkdocs_config, f)

src/nmdc_runtime/requirements.txt

@@ -0,0 +1 @@
+PyYAML==6.0.2