[PR #187] [MERGED] fix: grow short node descriptions to the 40-char floor #185

New issue

Closed

opened 2026-10-26 22:10:23 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:10:23 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/embedded-docs/pull/187
Author: @lin-bot23
Created: 10/17/2026
Status: ✅ Merged
Merged: 10/17/2026
Merged by: @comfyui-wiki

Base: main ← Head: fix/description-min-length

📝 Commits (1)

14c5c68 fix: grow short node descriptions to the 40-char floor

📊 Changes

2 files changed (+110 additions, -9 deletions)

View changed files

📝 docs-generation/scripts/sync_to_comfy_docs.py (+45 -4)
📝 docs-generation/tests/test_sync_helpers.py (+65 -5)

📄 Description

Fixes #186.

sync_to_comfy_docs.py seeds every frontmatter description from the first sentence of the first overview paragraph, then build_frontmatter() only caps it at 160 chars. Nothing grew a short seed, so localized pages that open with a one-liner shipped descriptions below the 40-char guideline in Comfy-Org/docs AGENTS.md. CJK says the same thing in fewer characters, which is why zh/ja carried most of it.

Change

_expand_to_minimum(): keep appending the following sentences from the same overview paragraph while the result is under _MIN_DESCRIPTION_CHARS and the next sentence still fits in MAX_DESCRIPTION_CHARS.
- extractive only: nothing invented, and when the paragraph runs out the short description stays as-is;
- when the next sentence does not fit in 160 chars, as much of it as fits is kept (same word/clause-aware cut _trim_to_length already applies to over-long sentences) rather than dropping back to the one-liner;
- _join_sentences() joins a CJK terminator (。！？) without a space and an ASCII one with a space;
- get_description_from_content() now returns the grown result (_trim_to_length is unchanged and stays a no-op on it).
Locale call site: dropped the 28-char f"Documentation for {node} node." seed. A localized page with no prose paragraph (zh-TW pages that open with ## 概述, for example) fell into it and shipped a short description; the empty value now reaches build_frontmatter(), which uses its own 40+ char templated fallback.

Verification

python3 docs-generation/tests/test_sync_helpers.py: 32 tests, OK. New DescriptionFloorTests covers growth, paragraph exhaustion, the 160 ceiling, an already-long first sentence, and the AI-disclaimer skip; three existing tests asserted "first sentence only" and were updated to their new expectation (two of them were rewritten with a first sentence that already clears the floor, so they still test what their names say).
Simulated the real code path (get_description_from_content → build_frontmatter → frontmatter value) over all 15,810 node docs in comfyui_embedded_docs/docs:

before after

descriptions under 40 chars 1,211 49

descriptions over 160 chars 0 0

The 49 residual pages have a whole opening paragraph shorter than the floor, so there is nothing left to append without inventing text. zh: 429 → 7, zh-TW: 351 → 13, ja: 125 → 4, ko: 87 → 2.
The MOSSImageLayoutPrompt case the issue was filed from: zh 22 → 106 chars, ja 33 → 107, ko 32 → 158.
docs-generation/tests/test_translation_fixes.py::test_persian_outputs_section_detected fails on origin/main as well (verified with the changes stashed), so it is pre-existing and untouched here.

	before	after
descriptions under 40 chars	1,211	49
descriptions over 160 chars	0	0

Follow-up

The generated pages in Comfy-Org/docs only change on the next sync; no hand edits to built-in-nodes/** are part of this PR.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/embedded-docs/pull/187 **Author:** [@lin-bot23](https://github.com/lin-bot23) **Created:** 10/17/2026 **Status:** ✅ Merged **Merged:** 10/17/2026 **Merged by:** [@comfyui-wiki](https://github.com/comfyui-wiki) **Base:** `main` ← **Head:** `fix/description-min-length` --- ### 📝 Commits (1) - [`14c5c68`](https://github.com/Comfy-Org/embedded-docs/commit/14c5c688826d6380734391527c76f941eda209fc) fix: grow short node descriptions to the 40-char floor ### 📊 Changes **2 files changed** (+110 additions, -9 deletions) <details> <summary>View changed files</summary> 📝 `docs-generation/scripts/sync_to_comfy_docs.py` (+45 -4) 📝 `docs-generation/tests/test_sync_helpers.py` (+65 -5) </details> ### 📄 Description Fixes #186. `sync_to_comfy_docs.py` seeds every frontmatter `description` from the first sentence of the first overview paragraph, then `build_frontmatter()` only caps it at 160 chars. Nothing grew a short seed, so localized pages that open with a one-liner shipped descriptions below the 40-char guideline in `Comfy-Org/docs` AGENTS.md. CJK says the same thing in fewer characters, which is why zh/ja carried most of it. ## Change - `_expand_to_minimum()`: keep appending the following sentences from the same overview paragraph while the result is under `_MIN_DESCRIPTION_CHARS` and the next sentence still fits in `MAX_DESCRIPTION_CHARS`. - extractive only: nothing invented, and when the paragraph runs out the short description stays as-is; - when the next sentence does not fit in 160 chars, as much of it as fits is kept (same word/clause-aware cut `_trim_to_length` already applies to over-long sentences) rather than dropping back to the one-liner; - `_join_sentences()` joins a CJK terminator (`。！？`) without a space and an ASCII one with a space; - `get_description_from_content()` now returns the grown result (`_trim_to_length` is unchanged and stays a no-op on it). - Locale call site: dropped the 28-char `f"Documentation for {node} node."` seed. A localized page with no prose paragraph (zh-TW pages that open with `## 概述`, for example) fell into it and shipped a short description; the empty value now reaches `build_frontmatter()`, which uses its own 40+ char templated fallback. ## Verification - `python3 docs-generation/tests/test_sync_helpers.py`: 32 tests, OK. New `DescriptionFloorTests` covers growth, paragraph exhaustion, the 160 ceiling, an already-long first sentence, and the AI-disclaimer skip; three existing tests asserted "first sentence only" and were updated to their new expectation (two of them were rewritten with a first sentence that already clears the floor, so they still test what their names say). - Simulated the real code path (`get_description_from_content` → `build_frontmatter` → frontmatter value) over all 15,810 node docs in `comfyui_embedded_docs/docs`: | | before | after | | --- | --- | --- | | descriptions under 40 chars | 1,211 | 49 | | descriptions over 160 chars | 0 | 0 | The 49 residual pages have a whole opening paragraph shorter than the floor, so there is nothing left to append without inventing text. zh: 429 → 7, zh-TW: 351 → 13, ja: 125 → 4, ko: 87 → 2. - The `MOSSImageLayoutPrompt` case the issue was filed from: zh 22 → 106 chars, ja 33 → 107, ko 32 → 158. - `docs-generation/tests/test_translation_fixes.py::test_persian_outputs_section_detected` fails on `origin/main` as well (verified with the changes stashed), so it is pre-existing and untouched here. ## Follow-up The generated pages in `Comfy-Org/docs` only change on the next sync; no hand edits to `built-in-nodes/**` are part of this PR. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 22:10:23 +00:00