Skip to content

docs: refresh README pipeline illustration#1448

Merged
MilagrosMarin merged 2 commits intomasterfrom
docs/landing-illustration-svg
May 5, 2026
Merged

docs: refresh README pipeline illustration#1448
MilagrosMarin merged 2 commits intomasterfrom
docs/landing-illustration-svg

Conversation

@dimitri-yatsenko
Copy link
Copy Markdown
Member

Summary

  • Replaces the pre-2.0 pipeline illustration in the README with the same new asset that lands in datajoint-docs (datajoint-docs#164).
  • Adds images/pipeline.svg as the editable source of truth — text in the repo, so the source can't go missing again.
  • Re-renders images/pipeline.png from the SVG so the README's existing raw-URL image link keeps working without edits. (GitHub serves raw .svg as text/plain, which doesn't render inline; PNG stays the safer display format for README.)
  • Removes images/pipeline.drawio — the stale source for the old PNG, now superseded by the SVG.

The new illustration uses calcium-imaging vocabulary matching the docs (SubjectSessionScanAverageFrameSegmentationActivity), follows DataJoint's notation (rectangles for Manual/Lookup, ovals for Imported/Computed), and shows 2.0 type syntax (int32, <blob@>).

Test plan

  • View the rendered README on this PR — confirm the new pipeline image displays correctly.
  • Verify shape convention: rectangles for Subject/Session/Scan/SegmentationParams; ovals for AverageFrame/Segmentation/Activity.
  • Verify code snippet uses int32 and <blob@>, not longblob/double.
  • Confirm no other docs or scripts reference pipeline.drawio (verified via grep at commit time).

Replace the pre-2.0 pipeline illustration in the README with the new
landing-page asset from datajoint-docs. The previous PNG bundled a
diagram and a code snippet using legacy type names (longblob, double)
and was rendered from a now-stale .drawio source.

- Add images/pipeline.svg as the editable source of truth (text in
  the repo — no separate file to lose).
- Re-render images/pipeline.png from the SVG so the existing README
  image link continues to work without changes (GitHub raw SVGs serve
  as text/plain and don't render inline; PNG remains the safer choice
  for README display).
- Remove images/pipeline.drawio — superseded by the SVG, no longer
  the source of truth.

The new illustration uses calcium-imaging vocabulary that matches the
docs (Subject/Session/Scan/AverageFrame/Segmentation/Activity), follows
DataJoint's notation (rectangles for Manual/Lookup, ovals for
Imported/Computed), and shows 2.0 type syntax (int32, <blob@>).
@MilagrosMarin
Copy link
Copy Markdown
Contributor

@dimitri-yatsenko, thanks for this PR. I have a couple of comments: (1) It seems the new image is much smaller than the previous one. Can you confirm it is visible and clear, with a font size of approximately 9-11 points? (2) In addition, I see that the comments on the right are set against a transparent background, while the make function text has a white background. This can be an issue if the background turns black, since the text is black too. Could these comments be set against a white background as well?

Address review feedback on the new landing-page illustration:

- Add an opaque white background rect covering the full viewBox so
  the entire illustration (annotations included) reads correctly
  against any page theme. Previously the code panel had its own white
  rect but the surrounding annotations sat on transparent — black
  text on a black page background made them invisible in GitHub's
  dark-mode README rendering.
- Bump the annotation font size from 17 to 19 to keep effective
  rendered text in the 9-11pt range when displayed at typical README
  column widths.

Re-render images/pipeline.png from the updated SVG.
@dimitri-yatsenko
Copy link
Copy Markdown
Member Author

Thanks for the careful review, @MilagrosMarin — both points were on the money.

Pushed db98bfa to address them:

  1. Added an opaque white <rect> covering the full SVG viewBox so the entire illustration (annotations included) renders against white regardless of page theme. The transparent gutters around the code panel made the right-side annotations invisible in GitHub's dark-mode README rendering — confirmed and fixed.
  2. Bumped the annotation font size from 17 to 19. At a typical README column width of ~800 px, that puts effective rendered size around 10 pt — within the 9–11 pt range you flagged. The diagram labels (22) and code (18) were already in range.

Re-rendered images/pipeline.png from the updated SVG, so the README image link reflects the fix without further edits. The same change is going up shortly in datajoint-docs as a follow-up PR.

@MilagrosMarin MilagrosMarin merged commit dfba749 into master May 5, 2026
3 checks passed
@MilagrosMarin MilagrosMarin deleted the docs/landing-illustration-svg branch May 5, 2026 16:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants