docs(diagram): renamed FKs as orange edges [blocked on v2.3.2 / dj-python#1508]#215
Draft
dimitri-yatsenko wants to merge 4 commits into
Draft
docs(diagram): renamed FKs as orange edges [blocked on v2.3.2 / dj-python#1508]#215dimitri-yatsenko wants to merge 4 commits into
dimitri-yatsenko wants to merge 4 commits into
Conversation
…s (#1492) Aligns the diagram-notation docs with the nx.MultiDiGraph migration (datajoint/datajoint-python#1508): - read-diagrams / model-relationships / schema-design: 'orange dots' -> 'orange edges'; hover tooltip lists the renamed columns. read-diagrams gains a 'Renamed primary vs. secondary foreign keys' example (Synapse/NeuronProfile) showing renamed FKs keep the line-style semantics: solid=primary, dashed=secondary, thick=1:1, thin=multi, in orange. - diagram.md: new Edge Styles row for the renamed-FK orange edge. - cascade.md / trace.md: internal-model prose updated from 'alias node' to the MultiDiGraph parallel-edge model (alias nodes no longer exist). read-diagrams and model-relationships notebooks re-executed against the #1508 build; SVGs now show orange edges with rename tooltips.
dimitri-yatsenko
added
the
documentation
…build Regenerates read-diagrams and model-relationships against datajoint-python #1508 at its final keyed-edge implementation (edges keyed by the FK-attribute tuple). Renamed FKs render as orange edges with rename tooltips; genuine parallel FKs (Person/Marriage, Neuron/Synapse, Session/Comparison) each show their two distinct edges — no duplication.
'subject' read like an animal identifier; 'profile_id' is clearer for a 1:1 profile extension of Neuron. Re-executed against the #1508 build.
mkdocs-jupyter does not run the admonition extension on notebook markdown cells, so the four '!!! version-added "New in 2.1"' blocks in read-diagrams rendered as literal text. Convert them to blockquote callouts that render in the notebook markdown pipeline. Markdown-only; no re-execution needed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Paired with datajoint/datajoint-python#1508 (nx.MultiDiGraph migration, milestone v2.3.2).
What changed
The diagram notation for a renamed / aliased foreign key changed: it used to
render as a small orange dot (an integer "alias node" between two tables); it
now renders as a distinctly-colored orange edge with a hover tooltip listing
the renamed columns (e.g.
spouse1 ← person_id). The alias node is gone from theunderlying graph entirely (it is now an
nx.MultiDiGraphwith parallel edges).Prose / notation
how-to/read-diagrams.ipynb,how-to/model-relationships.ipynb,tutorials/basics/02-schema-design.ipynb— "orange dots" → "orange edges";hover-tooltip wording updated.
reference/specs/diagram.md— new Edge Styles row for the renamed-FK orange edge.reference/specs/cascade.md,reference/specs/trace.md— internal-model proseupdated from the "alias node" mechanism to the MultiDiGraph parallel-edge model.
New example (shows the semantics are retained)
read-diagrams.ipynbgains a "Renamed primary vs. secondary foreign keys"subsection. Orange is layered on top of the usual line styles — it never overrides
them:
Person → Marriage(spouse1/spouse2)Neuron → Synapse(presynaptic/postsynaptic)Neuron → NeuronProfile(subject)Verification
read-diagramsandmodel-relationshipsnotebooks were re-executed against the#1508 build (MySQL via the repo's
docker composeEXECUTE flow). The committedSVGs now show
stroke="#ff8800"on the renamed-FK edges (withxlink:title="spouse1 ← person_id"tooltips) and no alias-node dots; solid/dashedand thick/thin encodings are preserved.
Follow-up (at release)
tutorials/domain/allen-ccf/allen-ccf.ipynbalso renders renamed-FK diagrams andstill shows the old dots; it will be picked up by the standard release-time full
notebook re-execution against the released v2.3.2 package, so it is intentionally
not re-run in this PR.