Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
Changes from 1 commit
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
3d4820b
WIP: Generate `refgraph` visualizations via GHA workflow
eecavanna Sep 27, 2024
9852362
Constrain Python version and regenerate `poetry.lock` file
eecavanna Sep 27, 2024
5ecdcd5
WIP: Inject `refgraph` pages into documentation preview site
eecavanna Sep 27, 2024
ea3794b
Install `refscan` via `pipx` instead of via `poetry`
eecavanna Sep 27, 2024
27754b1
Regenerate `poetry.lock` file (by running `$ poetry lock --no-update`)
eecavanna Sep 27, 2024
9c22098
Use correct directory name
eecavanna Sep 27, 2024
aa4843c
Remove comment to simplify PR diff
eecavanna Sep 27, 2024
80d509d
Remove unnecessary commands from GHA workflow
eecavanna Sep 27, 2024
d8ed9b3
Use `pipx run` to avoid installing anything
eecavanna Sep 27, 2024
4e753b9
Revert unnecessary changes to `poetry.lock` file
eecavanna Sep 27, 2024
9b750e1
WIP: Update site navigation bar so it contains links to graphs
eecavanna Sep 27, 2024
8915b2b
Restrict which `refscan` version will be used
eecavanna Sep 27, 2024
53a7875
Remove comment unrelated to other changes on branch
eecavanna Sep 27, 2024
168a3cc
Standardize comments between doc-related GHA workflows
eecavanna Sep 27, 2024
4da13d4
WIP: Populate project version number before generating derivative files
eecavanna Sep 27, 2024
472270e
Install `refscan` and update `gendoc` Makefile target to run `refgraph`
eecavanna Oct 15, 2024
8acd4c3
Remove `refgraph` step from GHA workflows (is handled by `make gendoc`)
eecavanna Oct 15, 2024
904ff38
Clarify comment
eecavanna Oct 15, 2024
9911c4c
Update sidebar link text to be more descriptive
eecavanna Oct 15, 2024
e5943a9
Introduce "Visualizations" page as an intermediate destination
eecavanna Oct 26, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Introduce "Visualizations" page as an intermediate destination
eecavanna committed Oct 26, 2024
commit e5943a9c065b50d451eac15882b6b2e1148cde87
7 changes: 3 additions & 4 deletions Makefile
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My two cents here is it will be confusing and not very useful to distribute the inter-class relationship diagram until we make the ranges as strict as the structured syntax patterns.

# 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

3 changes: 1 addition & 2 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -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
25 changes: 25 additions & 0 deletions src/docs/visualizations.md
Original file line number Diff line number Diff line change
@@ -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.