Stop docgen truncating slot/class descriptions mid-word (#3242)#3249
Stop docgen truncating slot/class descriptions mid-word (#3242)#3249turbomam wants to merge 1 commit into
Conversation
The docs templates ran every table-cell description through linkml
docgen's `enshorten` filter, which does description.split(".")[0]. Any
internal period, including abbreviations like "i.e." and "e.g.", was
treated as a sentence end, so has_raw_value rendered as "...in raw
form, i" and language as "...ISO 639-1 code e".
Replace enshorten with a local shorten macro (src/doc-templates/
_macros.jinja2) that collapses newlines, escapes pipes for table
safety, and caps length at a word boundary without splitting on
periods. Applied across the class, slot, enum, index, and subset
templates. Upstream fix tracked in linkml/linkml#3732.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
There was a problem hiding this comment.
Pull request overview
This PR fixes LinkML docgen output where class/slot/enum/subset table-cell descriptions were being truncated mid-word due to enshorten splitting on the first period (e.g., abbreviations like “i.e.” / “e.g.”). It replaces enshorten usage in the doc templates with a local shorten macro that truncates by length at a word boundary and also normalizes table-cell content for Markdown safety.
Changes:
- Added a shared Jinja2 macro (
shorten) to truncate description text without splitting on periods. - Updated the class/slot/enum/subset/index doc templates to use
shorten(...)instead of|enshorten. - Added basic table-safety transforms (newline collapse and pipe escaping) in the macro.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/doc-templates/_macros.jinja2 | Adds a shared shorten macro used by docs templates to avoid mid-word truncation and improve table safety. |
| src/doc-templates/class.md.jinja2 | Switches slot/class description table cells from enshorten to the new shorten macro. |
| src/doc-templates/slot.md.jinja2 | Switches class/slot description table cells from enshorten to shorten. |
| src/doc-templates/enum.md.jinja2 | Switches permissible value and slot description table cells from enshorten to shorten. |
| src/doc-templates/subset.md.jinja2 | Switches class/slot/enum description table cells from enshorten to shorten. |
| src/doc-templates/index.md.jinja2 | Switches index table description cells from enshorten to shorten across classes/slots/enums/types/subsets. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Acceptance-check page: https://microbiomedata.github.io/nmdc-schema/pr-preview/pr-3249/AttributeValue/
|
Fixes the mid-word truncation reported in #3242.
The class, slot, enum, index, and subset doc templates ran each table-cell description through linkml docgen's
enshortenfilter, which splits on the first period. Abbreviations like "i.e." and "e.g." were treated as sentence ends, sohas_raw_valuerendered as "...raw form, i" andlanguageas "...code e".This replaces
enshortenwith a localshortenmacro (src/doc-templates/_macros.jinja2) that caps length at a word boundary without splitting on periods, and collapses newlines and escapes pipes for table safety. Regenerating the docs confirmshas_raw_valueandlanguagenow show their full first sentence.Docs-build only: no schema or generated artifacts change. The upstream fix to
enshortenitself is tracked in linkml/linkml#3732; this is the local stopgap.Closes #3242