diff --git a/.github/workflows/fetch-and-compile-nmdc-runtime-documentation.yml b/.github/workflows/fetch-and-compile-nmdc-runtime-documentation.yml new file mode 100644 index 0000000..0ed5f73 --- /dev/null +++ b/.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 diff --git a/src/.gitignore b/src/.gitignore index e69de29..cbeda0e 100644 --- a/src/.gitignore +++ b/src/.gitignore @@ -0,0 +1,2 @@ +# Ignore all the `.venv` directories in the child directories of the current directory. +/*/.venv diff --git a/src/nmdc_runtime/modify_mkdocs_config.py b/src/nmdc_runtime/modify_mkdocs_config.py new file mode 100644 index 0000000..4072039 --- /dev/null +++ b/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) diff --git a/src/nmdc_runtime/requirements.txt b/src/nmdc_runtime/requirements.txt new file mode 100644 index 0000000..8392d54 --- /dev/null +++ b/src/nmdc_runtime/requirements.txt @@ -0,0 +1 @@ +PyYAML==6.0.2