Include inter-class and inter-collection relationship graphs in schema documentation

.github/workflows/deploy-docs.yaml

@@ -23,8 +23,34 @@ jobs:
       - name: Install dependencies.
         run: poetry install -E docs
 
-      - name: Build and deploy documentation.
-        # Build the docs and deploy them to GitHub Pages.
+      - 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
+        run: |
+          mkdir -p docs
+          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
         #       defined in `Makefile`. That target's action (i.e. recipe)
@@ -34,8 +60,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

.github/workflows/test_pages_build.yaml

@@ -31,13 +31,34 @@ jobs:
       - name: Install dependencies
         run: poetry install -E docs
 
-      - name: Build documentation
+      - 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: |
-          mkdir -p site
-          touch site/.nojekyll
+          poetry self add "poetry-dynamic-versioning[plugin]"
+          poetry dynamic-versioning
+          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 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:

mkdocs.yml

@@ -21,6 +21,7 @@ extra_javascript:
   - https://unpkg.com/[email protected]/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