From 3d4820bfac7f72ed292a7c631653927deaea1c41 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 17:44:00 -0700
Subject: [PATCH 01/20] WIP: Generate `refgraph` visualizations via GHA
 workflow

---
 .github/workflows/deploy-docs.yaml | 30 +++++++++++++++++++++++++-----
 pyproject.toml                     |  4 +++-
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index da85e72b5f..25dd6a41d6 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -21,10 +21,32 @@ jobs:
         uses: snok/install-poetry@v1.3
 
       - name: Install dependencies.
+        # Note: The `-E docs` option tells Poetry we want it to install the packages listed
+        #       in the "docs" list in the `tool.poetry.extras` section of `pyproject.toml`.
+        #       Reference: https://python-poetry.org/docs/main/pyproject#extras
         run: poetry install -E docs
 
-      - name: Build and deploy documentation.
-        # Build the docs and deploy them to GitHub Pages.
+      - name: Compile derivative files from source
+        # Note: `refgraph` requires a YAML file that gets generated here.
+        run: |
+          make squeaky-clean all
+
+      - name: Generate web-based documentation
+        run: |
+          mkdir -p docs
+          touch docs/.nojekyll
+          make gendoc
+
+      - name: Generate interactive schema visualizations
+        # Reference: https://github.com/microbiomedata/refscan
+        run: |
+          poetry run refgraph --version
+          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
+          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph docs/class-graph.html
+          head -10 docs/collection-graph.html
+          head -10 docs/class-graph.html
+
+        # Deploy the docs to GitHub Pages.
         #
         # Note: The `make mkd-gh-deploy` command below uses the `mkd-%` target
         #       defined in `Makefile`. That target's action (i.e. recipe)
@@ -34,8 +56,6 @@ jobs:
         #
         # Reference: https://www.mkdocs.org/user-guide/deploying-your-docs/
         #
+      - name: Deploy web-based documentation to GitHub Pages
         run: |
-          mkdir -p docs
-          touch docs/.nojekyll
-          make gendoc
           make mkd-gh-deploy
diff --git a/pyproject.toml b/pyproject.toml
index b85eb69dd6..712b337862 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -40,6 +40,7 @@ mkdocs-mermaid2-plugin = "^0.6.0"
 mkdocs-redirects = "^1.2.1"
 pymongo = "^4.7.2"
 ruamel-yaml = "^0.18.6"
+refscan = { version = ">=0.1.20", optional = true }
 
 [tool.poetry.group.dev.dependencies] # are some of these actually required as non-dev dependencies? # cruft for cookiecutter update could be installed with pipx?
 autopep8 = "^2.2.0"
@@ -91,8 +92,9 @@ patterns = [
 requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning"]
 build-backend = "poetry_dynamic_versioning.backend"
 
+# Reference: https://python-poetry.org/docs/main/pyproject#extras
 [tool.poetry.extras]
-docs = ["mkdocs-material"]
+docs = ["mkdocs-material", "refscan"]
 
 
 # scripts should have click clis

From 98523620c80659fd848060995ad79eff1b89f0d0 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 17:54:08 -0700
Subject: [PATCH 02/20] Constrain Python version and regenerate `poetry.lock`
 file

---
 poetry.lock    | 58 ++++++++++++++++++++++++++++++++++++++++++++------
 pyproject.toml |  2 +-
 2 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index a72699642a..887b83e201 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 1.8.2 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand.
 
 [[package]]
 name = "annotated-types"
@@ -1785,8 +1785,8 @@ files = [
 
 [package.dependencies]
 numpy = [
-    {version = ">=1.26.0", markers = "python_version >= \"3.12\""},
     {version = ">=1.22.4", markers = "python_version < \"3.11\""},
+    {version = ">=1.26.0", markers = "python_version >= \"3.12\""},
     {version = ">=1.23.2", markers = "python_version == \"3.11\""},
 ]
 python-dateutil = ">=2.8.2"
@@ -2028,8 +2028,8 @@ files = [
 annotated-types = ">=0.4.0"
 pydantic-core = "2.20.1"
 typing-extensions = [
-    {version = ">=4.12.2", markers = "python_version >= \"3.13\""},
     {version = ">=4.6.1", markers = "python_version < \"3.13\""},
+    {version = ">=4.12.2", markers = "python_version >= \"3.13\""},
 ]
 
 [package.extras]
@@ -2226,8 +2226,8 @@ files = [
 astroid = ">=3.2.2,<=3.3.0-dev0"
 colorama = {version = ">=0.4.5", markers = "sys_platform == \"win32\""}
 dill = [
-    {version = ">=0.3.7", markers = "python_version >= \"3.12\""},
     {version = ">=0.2", markers = "python_version < \"3.11\""},
+    {version = ">=0.3.7", markers = "python_version >= \"3.12\""},
     {version = ">=0.3.6", markers = "python_version >= \"3.11\" and python_version < \"3.12\""},
 ]
 isort = ">=4.2.5,<5.13.0 || >5.13.0,<6"
@@ -2514,7 +2514,6 @@ description = "A pure Python implementation of the trie data structure."
 optional = false
 python-versions = "*"
 files = [
-    {file = "PyTrie-0.4.0-py3-none-any.whl", hash = "sha256:f687c224ee8c66cda8e8628a903011b692635ffbb08d4b39c5f92b18eb78c950"},
     {file = "PyTrie-0.4.0.tar.gz", hash = "sha256:8f4488f402d3465993fb6b6efa09866849ed8cda7903b50647b7d0342b805379"},
 ]
 
@@ -2671,6 +2670,23 @@ files = [
 attrs = ">=22.2.0"
 rpds-py = ">=0.7.0"
 
+[[package]]
+name = "refscan"
+version = "0.1.20"
+description = "Command-line program that scans the NMDC MongoDB database for referential integrity violations"
+optional = true
+python-versions = "<4.0,>=3.10"
+files = [
+    {file = "refscan-0.1.20-py3-none-any.whl", hash = "sha256:b3f6808543ef05ee39675332e4486d49b057257c83f0a2c8d78ed57d87616331"},
+    {file = "refscan-0.1.20.tar.gz", hash = "sha256:52d1f2ce51790ab30932a5183fe7bec7683e8939b2979e0ff94833926a3af77b"},
+]
+
+[package.dependencies]
+linkml-runtime = ">=1.7.5,<2.0.0"
+pymongo = ">=4.7.1,<5.0.0"
+rich = ">=13.7.1,<14.0.0"
+typer = ">=0.12.3,<0.13.0"
+
 [[package]]
 name = "regex"
 version = "2024.5.15"
@@ -3119,6 +3135,17 @@ pandas = ">=1.3.4"
 pandasql = ">=0.7.3,<0.8.0"
 pygsheets = ">=2.0.5,<3.0.0"
 
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+description = "Tool to Detect Surrounding Shell"
+optional = true
+python-versions = ">=3.7"
+files = [
+    {file = "shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686"},
+    {file = "shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de"},
+]
+
 [[package]]
 name = "shexjsg"
 version = "0.8.2"
@@ -3421,6 +3448,23 @@ files = [
     {file = "trove_classifiers-2024.7.2.tar.gz", hash = "sha256:8328f2ac2ce3fd773cbb37c765a0ed7a83f89dc564c7d452f039b69249d0ac35"},
 ]
 
+[[package]]
+name = "typer"
+version = "0.12.5"
+description = "Typer, build great CLIs. Easy to code. Based on Python type hints."
+optional = true
+python-versions = ">=3.7"
+files = [
+    {file = "typer-0.12.5-py3-none-any.whl", hash = "sha256:62fe4e471711b147e3365034133904df3e235698399bc4de2b36c8579298d52b"},
+    {file = "typer-0.12.5.tar.gz", hash = "sha256:f592f089bedcc8ec1b974125d64851029c3b1af145f04aca64d69410f0c9b722"},
+]
+
+[package.dependencies]
+click = ">=8.0.0"
+rich = ">=10.11.0"
+shellingham = ">=1.3.0"
+typing-extensions = ">=3.7.4.3"
+
 [[package]]
 name = "types-python-dateutil"
 version = "2.9.0.20240316"
@@ -3664,9 +3708,9 @@ doc = ["furo", "jaraco.packaging (>=9.3)", "jaraco.tidelift (>=1.4)", "rst.linke
 test = ["big-O", "importlib-resources", "jaraco.functools", "jaraco.itertools", "jaraco.test", "more-itertools", "pytest (>=6,!=8.1.*)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-ignore-flaky", "pytest-mypy", "pytest-ruff (>=0.2.1)"]
 
 [extras]
-docs = ["mkdocs-material"]
+docs = ["mkdocs-material", "refscan"]
 
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.9"
-content-hash = "f94dee76c652cdd5b82853a7b7ed550c2c08dc803c5e543cfb4c05224e0ee73f"
+content-hash = "a16dd5379fb6d6a8cce03e6a02ea2ee751be031850ec192571e3bd46b8a9497c"
diff --git a/pyproject.toml b/pyproject.toml
index 712b337862..00a79f8abb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -40,7 +40,7 @@ mkdocs-mermaid2-plugin = "^0.6.0"
 mkdocs-redirects = "^1.2.1"
 pymongo = "^4.7.2"
 ruamel-yaml = "^0.18.6"
-refscan = { version = ">=0.1.20", optional = true }
+refscan = { version = ">=0.1.20", python = ">=3.10,<4.0", optional = true }
 
 [tool.poetry.group.dev.dependencies] # are some of these actually required as non-dev dependencies? # cruft for cookiecutter update could be installed with pipx?
 autopep8 = "^2.2.0"

From 5ecdcd5cdf9440db27352695c38febc1c56f7c8e Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 18:02:12 -0700
Subject: [PATCH 03/20] WIP: Inject `refgraph` pages into documentation preview
 site

---
 .github/workflows/test_pages_build.yaml | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index 8d32ab47c7..0fc11e45af 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -31,13 +31,25 @@ jobs:
       - name: Install dependencies
         run: poetry install -E docs
 
-      - name: Build documentation
+      - name: Compile derivative files from source
         run: |
-          mkdir -p site
-          touch site/.nojekyll
+          make squeaky-clean all
+
+      - name: Generate web-based documentation
+        run: |
+          mkdir -p docs
+          touch docs/.nojekyll
           make gendoc
           poetry run mkdocs build -d site
 
+      - name: Generate interactive schema visualizations
+        run: |
+          poetry run refgraph --version
+          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
+          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph site/class-graph.html
+          head -10 site/collection-graph.html
+          head -10 site/class-graph.html
+
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@v1
         with:

From ea3794b58acb4a91552c3b0c2c51711723c2c2f8 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:02:26 -0700
Subject: [PATCH 04/20] Install `refscan` via `pipx` instead of via `poetry`

---
 .github/workflows/deploy-docs.yaml      | 11 ++++++-----
 .github/workflows/test_pages_build.yaml |  7 ++++---
 pyproject.toml                          |  3 +--
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index 25dd6a41d6..fcd235ee7f 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -40,11 +40,12 @@ jobs:
       - name: Generate interactive schema visualizations
         # Reference: https://github.com/microbiomedata/refscan
         run: |
-          poetry run refgraph --version
-          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
-          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph docs/class-graph.html
-          head -10 docs/collection-graph.html
-          head -10 docs/class-graph.html
+          pipx install "refscan>=0.1.20,<1.0.0"
+          refgraph --version
+          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
+          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph site/class-graph.html
+          head -10 site/collection-graph.html
+          head -10 site/class-graph.html
 
         # Deploy the docs to GitHub Pages.
         #
diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index 0fc11e45af..ff71cb6f3c 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -44,9 +44,10 @@ jobs:
 
       - name: Generate interactive schema visualizations
         run: |
-          poetry run refgraph --version
-          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
-          poetry run refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph site/class-graph.html
+          pipx install "refscan>=0.1.20,<1.0.0"
+          refgraph --version
+          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
+          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph site/class-graph.html
           head -10 site/collection-graph.html
           head -10 site/class-graph.html
 
diff --git a/pyproject.toml b/pyproject.toml
index 00a79f8abb..0c69b95ff1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -40,7 +40,6 @@ mkdocs-mermaid2-plugin = "^0.6.0"
 mkdocs-redirects = "^1.2.1"
 pymongo = "^4.7.2"
 ruamel-yaml = "^0.18.6"
-refscan = { version = ">=0.1.20", python = ">=3.10,<4.0", optional = true }
 
 [tool.poetry.group.dev.dependencies] # are some of these actually required as non-dev dependencies? # cruft for cookiecutter update could be installed with pipx?
 autopep8 = "^2.2.0"
@@ -94,7 +93,7 @@ build-backend = "poetry_dynamic_versioning.backend"
 
 # Reference: https://python-poetry.org/docs/main/pyproject#extras
 [tool.poetry.extras]
-docs = ["mkdocs-material", "refscan"]
+docs = ["mkdocs-material"]
 
 
 # scripts should have click clis

From 27754b14b622e620bcdc78904088146cdd596d95 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:05:08 -0700
Subject: [PATCH 05/20] Regenerate `poetry.lock` file (by running `$ poetry
 lock --no-update`)

---
 poetry.lock | 49 ++-----------------------------------------------
 1 file changed, 2 insertions(+), 47 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index 887b83e201..d2811e650f 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -2670,23 +2670,6 @@ files = [
 attrs = ">=22.2.0"
 rpds-py = ">=0.7.0"
 
-[[package]]
-name = "refscan"
-version = "0.1.20"
-description = "Command-line program that scans the NMDC MongoDB database for referential integrity violations"
-optional = true
-python-versions = "<4.0,>=3.10"
-files = [
-    {file = "refscan-0.1.20-py3-none-any.whl", hash = "sha256:b3f6808543ef05ee39675332e4486d49b057257c83f0a2c8d78ed57d87616331"},
-    {file = "refscan-0.1.20.tar.gz", hash = "sha256:52d1f2ce51790ab30932a5183fe7bec7683e8939b2979e0ff94833926a3af77b"},
-]
-
-[package.dependencies]
-linkml-runtime = ">=1.7.5,<2.0.0"
-pymongo = ">=4.7.1,<5.0.0"
-rich = ">=13.7.1,<14.0.0"
-typer = ">=0.12.3,<0.13.0"
-
 [[package]]
 name = "regex"
 version = "2024.5.15"
@@ -3135,17 +3118,6 @@ pandas = ">=1.3.4"
 pandasql = ">=0.7.3,<0.8.0"
 pygsheets = ">=2.0.5,<3.0.0"
 
-[[package]]
-name = "shellingham"
-version = "1.5.4"
-description = "Tool to Detect Surrounding Shell"
-optional = true
-python-versions = ">=3.7"
-files = [
-    {file = "shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686"},
-    {file = "shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de"},
-]
-
 [[package]]
 name = "shexjsg"
 version = "0.8.2"
@@ -3448,23 +3420,6 @@ files = [
     {file = "trove_classifiers-2024.7.2.tar.gz", hash = "sha256:8328f2ac2ce3fd773cbb37c765a0ed7a83f89dc564c7d452f039b69249d0ac35"},
 ]
 
-[[package]]
-name = "typer"
-version = "0.12.5"
-description = "Typer, build great CLIs. Easy to code. Based on Python type hints."
-optional = true
-python-versions = ">=3.7"
-files = [
-    {file = "typer-0.12.5-py3-none-any.whl", hash = "sha256:62fe4e471711b147e3365034133904df3e235698399bc4de2b36c8579298d52b"},
-    {file = "typer-0.12.5.tar.gz", hash = "sha256:f592f089bedcc8ec1b974125d64851029c3b1af145f04aca64d69410f0c9b722"},
-]
-
-[package.dependencies]
-click = ">=8.0.0"
-rich = ">=10.11.0"
-shellingham = ">=1.3.0"
-typing-extensions = ">=3.7.4.3"
-
 [[package]]
 name = "types-python-dateutil"
 version = "2.9.0.20240316"
@@ -3708,9 +3663,9 @@ doc = ["furo", "jaraco.packaging (>=9.3)", "jaraco.tidelift (>=1.4)", "rst.linke
 test = ["big-O", "importlib-resources", "jaraco.functools", "jaraco.itertools", "jaraco.test", "more-itertools", "pytest (>=6,!=8.1.*)", "pytest-checkdocs (>=2.4)", "pytest-cov", "pytest-enabler (>=2.2)", "pytest-ignore-flaky", "pytest-mypy", "pytest-ruff (>=0.2.1)"]
 
 [extras]
-docs = ["mkdocs-material", "refscan"]
+docs = ["mkdocs-material"]
 
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.9"
-content-hash = "a16dd5379fb6d6a8cce03e6a02ea2ee751be031850ec192571e3bd46b8a9497c"
+content-hash = "f94dee76c652cdd5b82853a7b7ed550c2c08dc803c5e543cfb4c05224e0ee73f"

From 9c22098cfebe215787f61c06b25747ad15a2bc61 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:12:34 -0700
Subject: [PATCH 06/20] Use correct directory name

---
 .github/workflows/deploy-docs.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index fcd235ee7f..885df062e7 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -42,10 +42,10 @@ jobs:
         run: |
           pipx install "refscan>=0.1.20,<1.0.0"
           refgraph --version
-          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
-          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph site/class-graph.html
-          head -10 site/collection-graph.html
-          head -10 site/class-graph.html
+          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
+          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph docs/class-graph.html
+          head -10 docs/collection-graph.html
+          head -10 docs/class-graph.html
 
         # Deploy the docs to GitHub Pages.
         #

From aa4843c784c28b2b8226fd1d13e08110855e68a5 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:19:15 -0700
Subject: [PATCH 07/20] Remove comment to simplify PR diff

---
 pyproject.toml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/pyproject.toml b/pyproject.toml
index 0c69b95ff1..b85eb69dd6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -91,7 +91,6 @@ patterns = [
 requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning"]
 build-backend = "poetry_dynamic_versioning.backend"
 
-# Reference: https://python-poetry.org/docs/main/pyproject#extras
 [tool.poetry.extras]
 docs = ["mkdocs-material"]
 

From 80d509d5edbbbd9795ebcd86a3da92f4bca8e775 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:19:45 -0700
Subject: [PATCH 08/20] Remove unnecessary commands from GHA workflow

---
 .github/workflows/deploy-docs.yaml      | 3 ---
 .github/workflows/test_pages_build.yaml | 3 ---
 2 files changed, 6 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index 885df062e7..faf970fcdb 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -41,11 +41,8 @@ jobs:
         # Reference: https://github.com/microbiomedata/refscan
         run: |
           pipx install "refscan>=0.1.20,<1.0.0"
-          refgraph --version
           refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
           refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph docs/class-graph.html
-          head -10 docs/collection-graph.html
-          head -10 docs/class-graph.html
 
         # Deploy the docs to GitHub Pages.
         #
diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index ff71cb6f3c..ec2152a6a3 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -45,11 +45,8 @@ jobs:
       - name: Generate interactive schema visualizations
         run: |
           pipx install "refscan>=0.1.20,<1.0.0"
-          refgraph --version
           refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
           refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph site/class-graph.html
-          head -10 site/collection-graph.html
-          head -10 site/class-graph.html
 
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@v1

From d8ed9b349b1b0ff6c9c1ecb0fa3bcae34f5d3b22 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:21:19 -0700
Subject: [PATCH 09/20] Use `pipx run` to avoid installing anything

---
 .github/workflows/deploy-docs.yaml      | 5 ++---
 .github/workflows/test_pages_build.yaml | 5 ++---
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index faf970fcdb..989f30339f 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -40,9 +40,8 @@ jobs:
       - name: Generate interactive schema visualizations
         # Reference: https://github.com/microbiomedata/refscan
         run: |
-          pipx install "refscan>=0.1.20,<1.0.0"
-          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
-          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph docs/class-graph.html
+          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
+          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph docs/class-graph.html
 
         # Deploy the docs to GitHub Pages.
         #
diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index ec2152a6a3..9231ed8c50 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -44,9 +44,8 @@ jobs:
 
       - name: Generate interactive schema visualizations
         run: |
-          pipx install "refscan>=0.1.20,<1.0.0"
-          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
-          refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class --graph site/class-graph.html
+          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
+          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph site/class-graph.html
 
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@v1

From 4e753b98fb1ada145eea17e016d61c985ed86110 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:27:16 -0700
Subject: [PATCH 10/20] Revert unnecessary changes to `poetry.lock` file

---
 poetry.lock | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index d2811e650f..a72699642a 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.8.2 and should not be changed by hand.
 
 [[package]]
 name = "annotated-types"
@@ -1785,8 +1785,8 @@ files = [
 
 [package.dependencies]
 numpy = [
-    {version = ">=1.22.4", markers = "python_version < \"3.11\""},
     {version = ">=1.26.0", markers = "python_version >= \"3.12\""},
+    {version = ">=1.22.4", markers = "python_version < \"3.11\""},
     {version = ">=1.23.2", markers = "python_version == \"3.11\""},
 ]
 python-dateutil = ">=2.8.2"
@@ -2028,8 +2028,8 @@ files = [
 annotated-types = ">=0.4.0"
 pydantic-core = "2.20.1"
 typing-extensions = [
-    {version = ">=4.6.1", markers = "python_version < \"3.13\""},
     {version = ">=4.12.2", markers = "python_version >= \"3.13\""},
+    {version = ">=4.6.1", markers = "python_version < \"3.13\""},
 ]
 
 [package.extras]
@@ -2226,8 +2226,8 @@ files = [
 astroid = ">=3.2.2,<=3.3.0-dev0"
 colorama = {version = ">=0.4.5", markers = "sys_platform == \"win32\""}
 dill = [
-    {version = ">=0.2", markers = "python_version < \"3.11\""},
     {version = ">=0.3.7", markers = "python_version >= \"3.12\""},
+    {version = ">=0.2", markers = "python_version < \"3.11\""},
     {version = ">=0.3.6", markers = "python_version >= \"3.11\" and python_version < \"3.12\""},
 ]
 isort = ">=4.2.5,<5.13.0 || >5.13.0,<6"
@@ -2514,6 +2514,7 @@ description = "A pure Python implementation of the trie data structure."
 optional = false
 python-versions = "*"
 files = [
+    {file = "PyTrie-0.4.0-py3-none-any.whl", hash = "sha256:f687c224ee8c66cda8e8628a903011b692635ffbb08d4b39c5f92b18eb78c950"},
     {file = "PyTrie-0.4.0.tar.gz", hash = "sha256:8f4488f402d3465993fb6b6efa09866849ed8cda7903b50647b7d0342b805379"},
 ]
 

From 9b750e1345281e615a07abd35646cc3f5bef89d1 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:31:48 -0700
Subject: [PATCH 11/20] WIP: Update site navigation bar so it contains links to
 graphs

---
 mkdocs.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/mkdocs.yml b/mkdocs.yml
index c814d395dd..533601b12c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -21,6 +21,7 @@ extra_javascript:
   - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
   - javascripts/tablesort.js
 nav:
+  # Reference: https://www.mkdocs.org/user-guide/configuration/#nav
   - NMDC Schema: index.md
   - About: about.md
   - How to run a collaborative data modeling project: https://linkml.io/linkml/howtos/collaborative-development.html
@@ -30,6 +31,8 @@ nav:
   - NMDC Schema Contributors How-to from Schema Hackathon 2023-12-10: https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693
   - NMDC Schema Validation: schema-validation.md
   - Schema element deprecation guide: schema_element_deprecation_guide.md
+  - Class graph: class-graph.html
+  - Collection graph: collection-graph.html
 
 
 site_url: https://microbiomedata.github.io/nmdc-schema

From 8915b2bb18dbef3259fba57e5590b3ff4fb4de3a Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:34:09 -0700
Subject: [PATCH 12/20] Restrict which `refscan` version will be used

---
 .github/workflows/deploy-docs.yaml      | 4 ++--
 .github/workflows/test_pages_build.yaml | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index 989f30339f..ae85924d40 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -40,8 +40,8 @@ jobs:
       - name: Generate interactive schema visualizations
         # Reference: https://github.com/microbiomedata/refscan
         run: |
-          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
-          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph docs/class-graph.html
+          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
+          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph docs/class-graph.html
 
         # Deploy the docs to GitHub Pages.
         #
diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index 9231ed8c50..195e9b6f07 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -44,8 +44,8 @@ jobs:
 
       - name: Generate interactive schema visualizations
         run: |
-          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
-          pipx run --spec "refscan>=0.1.20,<1.0.0" refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph site/class-graph.html
+          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
+          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph site/class-graph.html
 
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@v1

From 53a78751ee930582aaf24c4fc7cac3cbab8de4a1 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 19:59:18 -0700
Subject: [PATCH 13/20] Remove comment unrelated to other changes on branch

---
 .github/workflows/deploy-docs.yaml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index ae85924d40..6e9a3617de 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -21,9 +21,6 @@ jobs:
         uses: snok/install-poetry@v1.3
 
       - name: Install dependencies.
-        # Note: The `-E docs` option tells Poetry we want it to install the packages listed
-        #       in the "docs" list in the `tool.poetry.extras` section of `pyproject.toml`.
-        #       Reference: https://python-poetry.org/docs/main/pyproject#extras
         run: poetry install -E docs
 
       - name: Compile derivative files from source

From 168a3ccdb72ff55bfb9b2e09fef5907c00d13942 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 23:11:52 -0700
Subject: [PATCH 14/20] Standardize comments between doc-related GHA workflows

---
 .github/workflows/deploy-docs.yaml      | 12 +++++++++---
 .github/workflows/test_pages_build.yaml | 12 ++++++++++--
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index 6e9a3617de..735026c0af 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -23,8 +23,7 @@ jobs:
       - name: Install dependencies.
         run: poetry install -E docs
 
-      - name: Compile derivative files from source
-        # Note: `refgraph` requires a YAML file that gets generated here.
+      - name: Derive files from sources
         run: |
           make squeaky-clean all
 
@@ -34,8 +33,15 @@ jobs:
           touch docs/.nojekyll
           make gendoc
 
-      - name: Generate interactive schema visualizations
+      - name: Generate reference graphs
+        # Use `refgraph` (part of `refscan`) to generate graphs (i.e. network diagrams)
+        # depicting the relationships between collections and between classes.
+        #
+        # Note: We generate the graphs (i.e. the HTML files) within the directory that
+        #       will eventually be deployed to GitHub Pages.
+        #
         # Reference: https://github.com/microbiomedata/refscan
+        #
         run: |
           pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
           pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph docs/class-graph.html
diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index 195e9b6f07..8c2feff8e9 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: poetry install -E docs
 
-      - name: Compile derivative files from source
+      - name: Derive files from sources
         run: |
           make squeaky-clean all
 
@@ -42,7 +42,15 @@ jobs:
           make gendoc
           poetry run mkdocs build -d site
 
-      - name: Generate interactive schema visualizations
+      - name: Generate reference graphs
+        # Use `refgraph` (part of `refscan`) to generate graphs (i.e. network diagrams)
+        # depicting the relationships between collections and between classes.
+        #
+        # Note: We generate the graphs (i.e. the HTML files) within the directory that
+        #       will eventually be deployed to GitHub Pages.
+        #
+        # Reference: https://github.com/microbiomedata/refscan
+        #
         run: |
           pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
           pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph site/class-graph.html

From 4da13d497684c03a7b33e99d853ae2ee9ede7c40 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Thu, 26 Sep 2024 23:27:47 -0700
Subject: [PATCH 15/20] WIP: Populate project version number before generating
 derivative files

---
 .github/workflows/deploy-docs.yaml      | 4 ++++
 .github/workflows/test_pages_build.yaml | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index 735026c0af..d7cc940263 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -24,7 +24,11 @@ jobs:
         run: poetry install -E docs
 
       - name: Derive files from sources
+        # Note: First, we replace the "0.0.0" placeholder version number in `pyproject.toml`.
+        # Reference: https://github.com/mtkennerly/poetry-dynamic-versioning/blob/master/README.md#command-line-mode
         run: |
+          poetry self add "poetry-dynamic-versioning[plugin]"
+          poetry dynamic-versioning
           make squeaky-clean all
 
       - name: Generate web-based documentation
diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index 8c2feff8e9..0e73d258ea 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -32,7 +32,11 @@ jobs:
         run: poetry install -E docs
 
       - name: Derive files from sources
+        # Note: First, we replace the "0.0.0" placeholder version number in `pyproject.toml`.
+        # Reference: https://github.com/mtkennerly/poetry-dynamic-versioning/blob/master/README.md#command-line-mode
         run: |
+          poetry self add "poetry-dynamic-versioning[plugin]"
+          poetry dynamic-versioning
           make squeaky-clean all
 
       - name: Generate web-based documentation

From 472270e56c99483e1cf00f4dfce6a97ccb56380a Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Mon, 14 Oct 2024 17:58:52 -0700
Subject: [PATCH 16/20] Install `refscan` and update `gendoc` Makefile target
 to run `refgraph`

---
 Makefile       |  6 ++++++
 poetry.lock    | 56 +++++++++++++++++++++++++++++++++++++++++++++-----
 pyproject.toml |  1 +
 3 files changed, 58 insertions(+), 5 deletions(-)

diff --git a/Makefile b/Makefile
index 7022a234c1..8ed740a4e4 100644
--- a/Makefile
+++ b/Makefile
@@ -155,6 +155,8 @@ $(PYMODEL):
 $(DOCDIR):
 	mkdir -p $@
 
+# Compile static Markdown files, images, and JavaScript scripts, into a documentation website.
+# Then, use `refgraph` to generate diagrams at the paths referenced in the `nav` section of `mkdocs.yml`.
 gendoc: $(DOCDIR)
 	# added copying of images and renaming of TEMP.md
 	cp $(SRC)/docs/*md $(DOCDIR) ; \
@@ -162,6 +164,10 @@ gendoc: $(DOCDIR)
 	$(RUN) gen-doc -d $(DOCDIR) --template-directory $(SRC)/$(TEMPLATEDIR) --include src/schema/deprecated.yaml $(SOURCE_SCHEMA_PATH)
 	mkdir -p $(DOCDIR)/javascripts
 	$(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/
+	# Use `refgraph` (part of `refscan`) to generate interactive diagrams within the compiled documentation file tree.
+	# One diagram depicts the relationships between collections and the other depicts the relationships between classes.
+	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph $(DOCDIR)/collection-graph.html
+	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph $(DOCDIR)/class-graph.html
 
 testdoc: gendoc serve
 
diff --git a/poetry.lock b/poetry.lock
index a72699642a..105e6fd613 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 1.8.2 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand.
 
 [[package]]
 name = "annotated-types"
@@ -1534,6 +1534,7 @@ optional = false
 python-versions = ">=3.6"
 files = [
     {file = "mkdocs-redirects-1.2.1.tar.gz", hash = "sha256:9420066d70e2a6bb357adf86e67023dcdca1857f97f07c7fe450f8f1fb42f861"},
+    {file = "mkdocs_redirects-1.2.1-py3-none-any.whl", hash = "sha256:497089f9e0219e7389304cffefccdfa1cac5ff9509f2cb706f4c9b221726dffb"},
 ]
 
 [package.dependencies]
@@ -1785,8 +1786,8 @@ files = [
 
 [package.dependencies]
 numpy = [
-    {version = ">=1.26.0", markers = "python_version >= \"3.12\""},
     {version = ">=1.22.4", markers = "python_version < \"3.11\""},
+    {version = ">=1.26.0", markers = "python_version >= \"3.12\""},
     {version = ">=1.23.2", markers = "python_version == \"3.11\""},
 ]
 python-dateutil = ">=2.8.2"
@@ -2028,8 +2029,8 @@ files = [
 annotated-types = ">=0.4.0"
 pydantic-core = "2.20.1"
 typing-extensions = [
-    {version = ">=4.12.2", markers = "python_version >= \"3.13\""},
     {version = ">=4.6.1", markers = "python_version < \"3.13\""},
+    {version = ">=4.12.2", markers = "python_version >= \"3.13\""},
 ]
 
 [package.extras]
@@ -2226,8 +2227,8 @@ files = [
 astroid = ">=3.2.2,<=3.3.0-dev0"
 colorama = {version = ">=0.4.5", markers = "sys_platform == \"win32\""}
 dill = [
-    {version = ">=0.3.7", markers = "python_version >= \"3.12\""},
     {version = ">=0.2", markers = "python_version < \"3.11\""},
+    {version = ">=0.3.7", markers = "python_version >= \"3.12\""},
     {version = ">=0.3.6", markers = "python_version >= \"3.11\" and python_version < \"3.12\""},
 ]
 isort = ">=4.2.5,<5.13.0 || >5.13.0,<6"
@@ -2671,6 +2672,23 @@ files = [
 attrs = ">=22.2.0"
 rpds-py = ">=0.7.0"
 
+[[package]]
+name = "refscan"
+version = "0.1.21"
+description = "Command-line program that scans the NMDC MongoDB database for referential integrity violations"
+optional = false
+python-versions = "<4.0,>=3.9"
+files = [
+    {file = "refscan-0.1.21-py3-none-any.whl", hash = "sha256:acb211a5621c5ecec8f9b129e3fcc60ec559898535e0068913d20e4f0c7d5be2"},
+    {file = "refscan-0.1.21.tar.gz", hash = "sha256:36ade37ba227ad7c45d5668039d219e41cd8530dbc0400ca9d5a52b60a9207e2"},
+]
+
+[package.dependencies]
+linkml-runtime = ">=1.7.5,<2.0.0"
+pymongo = ">=4.7.1,<5.0.0"
+rich = ">=13.7.1,<14.0.0"
+typer = ">=0.12.3,<0.13.0"
+
 [[package]]
 name = "regex"
 version = "2024.5.15"
@@ -3119,6 +3137,17 @@ pandas = ">=1.3.4"
 pandasql = ">=0.7.3,<0.8.0"
 pygsheets = ">=2.0.5,<3.0.0"
 
+[[package]]
+name = "shellingham"
+version = "1.5.4"
+description = "Tool to Detect Surrounding Shell"
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686"},
+    {file = "shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de"},
+]
+
 [[package]]
 name = "shexjsg"
 version = "0.8.2"
@@ -3421,6 +3450,23 @@ files = [
     {file = "trove_classifiers-2024.7.2.tar.gz", hash = "sha256:8328f2ac2ce3fd773cbb37c765a0ed7a83f89dc564c7d452f039b69249d0ac35"},
 ]
 
+[[package]]
+name = "typer"
+version = "0.12.5"
+description = "Typer, build great CLIs. Easy to code. Based on Python type hints."
+optional = false
+python-versions = ">=3.7"
+files = [
+    {file = "typer-0.12.5-py3-none-any.whl", hash = "sha256:62fe4e471711b147e3365034133904df3e235698399bc4de2b36c8579298d52b"},
+    {file = "typer-0.12.5.tar.gz", hash = "sha256:f592f089bedcc8ec1b974125d64851029c3b1af145f04aca64d69410f0c9b722"},
+]
+
+[package.dependencies]
+click = ">=8.0.0"
+rich = ">=10.11.0"
+shellingham = ">=1.3.0"
+typing-extensions = ">=3.7.4.3"
+
 [[package]]
 name = "types-python-dateutil"
 version = "2.9.0.20240316"
@@ -3669,4 +3715,4 @@ docs = ["mkdocs-material"]
 [metadata]
 lock-version = "2.0"
 python-versions = "^3.9"
-content-hash = "f94dee76c652cdd5b82853a7b7ed550c2c08dc803c5e543cfb4c05224e0ee73f"
+content-hash = "75bd51f270387b3f9d69f7087804d4861c5b1847a8a708b6ca42a570efd0ed6f"
diff --git a/pyproject.toml b/pyproject.toml
index b85eb69dd6..fb3b79600f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -63,6 +63,7 @@ sheets_and_friends = "^0.5.0" # for do_shuttle (and possibly more)
 sparql-burger = "^1.0.2"
 sparql-dataframe = "^0.4"
 vulture = "^2.11"
+refscan = "==0.1.21"
 
 
 #oaklib = "^0.5.24"

From 8acd4c3f84cb478e4a1b8f9e1fd17dc594cf1e78 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Mon, 14 Oct 2024 18:05:45 -0700
Subject: [PATCH 17/20] Remove `refgraph` step from GHA workflows (is handled
 by `make gendoc`)

---
 .github/workflows/deploy-docs.yaml      | 13 -------------
 .github/workflows/test_pages_build.yaml | 13 -------------
 Makefile                                |  7 ++++++-
 3 files changed, 6 insertions(+), 27 deletions(-)

diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
index d7cc940263..0a218350b4 100644
--- a/.github/workflows/deploy-docs.yaml
+++ b/.github/workflows/deploy-docs.yaml
@@ -37,19 +37,6 @@ jobs:
           touch docs/.nojekyll
           make gendoc
 
-      - name: Generate reference graphs
-        # Use `refgraph` (part of `refscan`) to generate graphs (i.e. network diagrams)
-        # depicting the relationships between collections and between classes.
-        #
-        # Note: We generate the graphs (i.e. the HTML files) within the directory that
-        #       will eventually be deployed to GitHub Pages.
-        #
-        # Reference: https://github.com/microbiomedata/refscan
-        #
-        run: |
-          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph docs/collection-graph.html
-          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph docs/class-graph.html
-
         # Deploy the docs to GitHub Pages.
         #
         # Note: The `make mkd-gh-deploy` command below uses the `mkd-%` target
diff --git a/.github/workflows/test_pages_build.yaml b/.github/workflows/test_pages_build.yaml
index 0e73d258ea..b6cbc1c69b 100644
--- a/.github/workflows/test_pages_build.yaml
+++ b/.github/workflows/test_pages_build.yaml
@@ -46,19 +46,6 @@ jobs:
           make gendoc
           poetry run mkdocs build -d site
 
-      - name: Generate reference graphs
-        # Use `refgraph` (part of `refscan`) to generate graphs (i.e. network diagrams)
-        # depicting the relationships between collections and between classes.
-        #
-        # Note: We generate the graphs (i.e. the HTML files) within the directory that
-        #       will eventually be deployed to GitHub Pages.
-        #
-        # Reference: https://github.com/microbiomedata/refscan
-        #
-        run: |
-          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph site/collection-graph.html
-          pipx run --spec 'refscan==0.1.20' refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph site/class-graph.html
-
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@v1
         with:
diff --git a/Makefile b/Makefile
index 8ed740a4e4..561984aa85 100644
--- a/Makefile
+++ b/Makefile
@@ -156,7 +156,12 @@ $(DOCDIR):
 	mkdir -p $@
 
 # Compile static Markdown files, images, and JavaScript scripts, into a documentation website.
-# Then, use `refgraph` to generate diagrams at the paths referenced in the `nav` section of `mkdocs.yml`.
+#
+# Then, use `refgraph` (part of `refscan`) to generate a pair of graphs (i.e. network diagrams),
+# one that depicts inter-collection relationships and one that depicts inter-class relationships.
+# We generate them (i.e. their HTML files) at paths referenced in the `nav` section of `mkdocs.yml`,
+# making it so that they appear when the user clicks on the associated sidebar navigation links.
+#
 gendoc: $(DOCDIR)
 	# added copying of images and renaming of TEMP.md
 	cp $(SRC)/docs/*md $(DOCDIR) ; \

From 904ff38c79990a4adc2e83101e1eed8f11f1a2b0 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Mon, 14 Oct 2024 18:09:17 -0700
Subject: [PATCH 18/20] Clarify comment

---
 Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 561984aa85..3b14c01538 100644
--- a/Makefile
+++ b/Makefile
@@ -159,8 +159,8 @@ $(DOCDIR):
 #
 # Then, use `refgraph` (part of `refscan`) to generate a pair of graphs (i.e. network diagrams),
 # one that depicts inter-collection relationships and one that depicts inter-class relationships.
-# We generate them (i.e. their HTML files) at paths referenced in the `nav` section of `mkdocs.yml`,
-# making it so that they appear when the user clicks on the associated sidebar navigation links.
+# We generate them (i.e. their HTML files) at paths referenced in the `nav` section of `mkdocs.yml`.
+# As a result, a pair of navigation links in the sidebar of the document website will lead to them.
 #
 gendoc: $(DOCDIR)
 	# added copying of images and renaming of TEMP.md

From 9911c4cfc669aa06bb8fb64f469628ef7f8548a7 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Mon, 14 Oct 2024 18:29:38 -0700
Subject: [PATCH 19/20] Update sidebar link text to be more descriptive

---
 mkdocs.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 533601b12c..938d27fc0b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,8 +31,8 @@ nav:
   - NMDC Schema Contributors How-to from Schema Hackathon 2023-12-10: https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693
   - NMDC Schema Validation: schema-validation.md
   - Schema element deprecation guide: schema_element_deprecation_guide.md
-  - Class graph: class-graph.html
-  - Collection graph: collection-graph.html
+  - Inter-class relationships (diagram): class-graph.html
+  - Inter-collection relationships (diagram): collection-graph.html
 
 
 site_url: https://microbiomedata.github.io/nmdc-schema

From e5943a9c065b50d451eac15882b6b2e1148cde87 Mon Sep 17 00:00:00 2001
From: eecavanna <eecavanna@users.noreply.github.com>
Date: Sat, 26 Oct 2024 15:11:36 -0700
Subject: [PATCH 20/20] Introduce "Visualizations" page as an intermediate
 destination

---
 Makefile                   |  7 +++----
 mkdocs.yml                 |  3 +--
 src/docs/visualizations.md | 25 +++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 6 deletions(-)
 create mode 100644 src/docs/visualizations.md

diff --git a/Makefile b/Makefile
index 3b14c01538..928260ae3e 100644
--- a/Makefile
+++ b/Makefile
@@ -159,8 +159,6 @@ $(DOCDIR):
 #
 # Then, use `refgraph` (part of `refscan`) to generate a pair of graphs (i.e. network diagrams),
 # one that depicts inter-collection relationships and one that depicts inter-class relationships.
-# We generate them (i.e. their HTML files) at paths referenced in the `nav` section of `mkdocs.yml`.
-# As a result, a pair of navigation links in the sidebar of the document website will lead to them.
 #
 gendoc: $(DOCDIR)
 	# added copying of images and renaming of TEMP.md
@@ -171,8 +169,9 @@ gendoc: $(DOCDIR)
 	$(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/
 	# Use `refgraph` (part of `refscan`) to generate interactive diagrams within the compiled documentation file tree.
 	# One diagram depicts the relationships between collections and the other depicts the relationships between classes.
-	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph $(DOCDIR)/collection-graph.html
-	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph $(DOCDIR)/class-graph.html
+	mkdir -p $(DOCDIR)/visualizations
+	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject collection --graph $(DOCDIR)/visualizations/collection-graph.html
+	$(RUN) refgraph --schema nmdc_schema/nmdc_materialized_patterns.yaml --subject class      --graph $(DOCDIR)/visualizations/class-graph.html
 
 testdoc: gendoc serve
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 938d27fc0b..f6c4040471 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,8 +31,7 @@ nav:
   - NMDC Schema Contributors How-to from Schema Hackathon 2023-12-10: https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693
   - NMDC Schema Validation: schema-validation.md
   - Schema element deprecation guide: schema_element_deprecation_guide.md
-  - Inter-class relationships (diagram): class-graph.html
-  - Inter-collection relationships (diagram): collection-graph.html
+  - Visualizations: visualizations.md
 
 
 site_url: https://microbiomedata.github.io/nmdc-schema
diff --git a/src/docs/visualizations.md b/src/docs/visualizations.md
new file mode 100644
index 0000000000..9f92928337
--- /dev/null
+++ b/src/docs/visualizations.md
@@ -0,0 +1,25 @@
+# Visualizations
+
+## Inter-collection relationship diagram
+
+<!-- Note: `visualizations/collection-graph.html` does not exist in the source code repository.
+           It gets generated as part of the documentation build process. -->
+This [**inter-collection relationship diagram**](visualizations/collection-graph.html)
+shows the database **collections** described by the schema, and the **relationships** between those collections.
+
+Each circle represents a collection.
+Each arrow represents all of the fields that documents in one collection—the one at that arrow's tail—can
+use to refer to documents in another collection—the one at that arrow's head.
+If you click on a circle, the names of the fields will appear on the arrows connected to that circle.
+
+## Inter-class relationship diagram
+
+<!-- Note: `visualizations/class-graph.html` does not exist in the source code repository.
+           It gets generated as part of the documentation build process. -->
+This [**inter-class relationship diagram**](visualizations/class-graph.html)
+shows the **classes** defined within the schema, and the **relationships** between those classes.
+
+Each circle represents a class.
+Each arrow represents all of the slots that instances of that class—the one at that arrow's tail—can
+use to refer to instances of another class—the one at that arrow's head.
+If you click on a circle, the names of the slots will appear on the arrows connected to that circle.