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

.github/workflows/deploy-docs.yaml

@@ -23,8 +23,21 @@ 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
+
+        # 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 +47,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,10 +31,18 @@ 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
 

Makefile

@@ -155,13 +155,23 @@ $(PYMODEL):
 $(DOCDIR):
 	mkdir -p $@
 
+# Compile static Markdown files, images, and JavaScript scripts, into a documentation website.
+#
+# 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.
+#
 gendoc: $(DOCDIR)
 	# added copying of images and renaming of TEMP.md
 	cp $(SRC)/docs/*md $(DOCDIR) ; \
 	cp -r $(SRC)/docs/images $(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.
+	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
 

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,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
+  - Visualizations: visualizations.md
 
 
 site_url: https://microbiomedata.github.io/nmdc-schema

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"

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.