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

[eecavanna]

In this branch, I updated two GitHub Actions workflows—one that builds and deploys the production documentation website and one that builds and deploys the preview documentation website—so that they use refgraph (part of refscan, a homegrown referential integrity checker tool) to generate a pair of diagrams and include them in the resulting schema documentation.

Specifically, the workflows run $ pipx run refgraph {options} to generate a graph (a.k.a. network diagram) in which the circles (nodes) represent Mongo collections and the arrows (edges) represent relationships between those collections. An arrow from circle A to circle B means that the schema allows a document in collection A to contain a reference to a document in collection B.

Similarly, the workflows then run $ pipx run refgraph {different options} to generate a graph where the circles (nodes) represent classes instead of collections.

The graphs are web-based and are stored in files named:

• collection-graph.html
• class-graph.html

Both graphs (files) are injected into the schema documentation website's file tree at "build time" (i.e. when the GitHub Actions workflow is compiling the schema documentation website from source). They are not stored in the repository.

Finally, I updated the MkDocs configuration file so that the website's left-hand sidebar contains hyperlinks to the two graphs.

Screenshots

Two new links in the sidebar:

class-graph.html:

collection-graph.html:

[github-actions]

PR Preview Action v1.4.8
🚀 Deployed preview to https://microbiomedata.github.io/berkeley-schema-fy24/pr-preview/pr-265/
on branch gh-pages at 2024-10-26 22:15 UTC

[eecavanna]

⚠️ The PR preview documentation site for this PR doesn't work anymore (at least not at: https://microbiomedata.github.io/berkeley-schema-fy24/pr-preview/pr-265/). I think, when someone else opens a PR, the "PR Preview Actions" will clobber any existing preview site.

[eecavanna]

These 3 lines were moved to an earlier step (i.e. to lines 36-38) so that a documentation website file tree exists by the time we try to inject the graphs into it (i.e. on lines 50-51).

[eecavanna]

I noticed that this command is present in this test_pages_build.yaml file, but not in the deploy-docs.yaml file. I don't know why it's necessary in one situation, but not the other. Maybe it's because the author wanted the documentation website's file tree to also be generated in a directory named site (instead of—or in addition to—the default directory).

[eecavanna]

I'm OK with this being merged after the Berkeley Schema Roll Out is done (i.e. after October 15, 2024). I'm interested in getting feedback/input before then.

[eecavanna]

If microbiomedata#2198 gets merged into nmdc-schema/main, then I will consider this PR to be redundant and will close it.

[eecavanna]

Closing because there is a pair of PRs in the upstream nmdc-schema repo that, together, cover what this one did. In addition, one of those PRs has already been merged into that repo. So, this PR is redundant.