[PR #188] [MERGED] fix: description extraction skips plain-paragraph disclaimers and reads overview H2s #188

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

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

Base: main ← Head: fix/desc-disclaimer-ja

📝 Commits (3)

9911c53 fix: skip plain-paragraph AI disclaimers when building descriptions
74add05 fix: read the overview from an overview H2 when the page has no lead paragraph
d5c3848 fix: require AI wording in the English disclaimer matcher

📊 Changes

2 files changed (+132 additions, -7 deletions)

View changed files

📝 docs-generation/scripts/sync_to_comfy_docs.py (+59 -7)
📝 docs-generation/tests/test_sync_helpers.py (+73 -0)

📄 Description

Summary

Two defects in the description extractor made localized node pages ship meta descriptions that describe nothing.

1. Plain-paragraph AI disclaimers became the description. get_description_from_content() only skipped the disclaimer when the page wrote it as a blockquote (> ...). The ja and zh pages ship it as a plain opening paragraph, and the line also carries the [GitHubで編集する](...) / [在GitHub上编辑](...) link. On the docs site 27 ja pages and 1 zh page used the disclaimer as their whole description:

ja/built-in-nodes/CaseConverter.mdx → このドキュメントはAIによって生成されました。
ja/built-in-nodes/StringConcatenate.mdx → このドキュメントはAI生成です。

After #187 grew short descriptions to the 40-char floor these got worse, because the growth pulled the "edit on GitHub" URL into the 160-char window.

2. Pages whose overview sits under an H2 fell back to the English template. 30 nodes write the overview as ## 概述 / ## 概要 / ## 개요 / ## Overview instead of a lead paragraph under the H1. The extractor broke on the first H2, produced an empty description, and build_frontmatter() filled in "Complete documentation for the X node in ComfyUI. Learn its inputs, outputs, parameters and usage." on zh/ja/ko pages (120 pages).

Changes

docs-generation/scripts/sync_to_comfy_docs.py
- DISCLAIMER_LINE matches the disclaimer opening in every shipped language (This document was generated…, 此文档由 AI…, このドキュメントは AI…, 이 문서는 AI…), blockquote or plain paragraph. The old blockquote check is kept as _BLOCKQUOTE_AI_DISCLAIMER for pages that use the quote form with other wording.
- _is_overview_heading() / _OVERVIEW_HEADINGS: before any prose has been collected, an overview-style H2 is entered instead of ending the scan; a later ## Overview therefore cannot hijack text that already started under the H1. Doubled-hash headings (## ## 概述, a known translation artifact) are normalised.
- Prose that merely mentions AI-generated content is untouched (This node applies AI-generated textures…).
docs-generation/tests/test_sync_helpers.py: 8 regression tests covering the ja/zh plain-paragraph disclaimer (with the GitHub link), the English wording This document is AI-generated / was generated with AI, ordinary prose like This document was written to explain the node (kept, not skipped), a legitimate AI-generated mention, overview H2s in zh/ja/ko/en, the doubled-hash heading, and ## Inputs first (template fallback remains correct there).

Verification

python3 -m unittest tests.test_sync_helpers → 40 tests OK.
Full sync_to_comfy_docs.py --mode all against a docs worktree:
- 0 of 853 generated descriptions contain AI-generated / AI生成 / AI에 / AIによって / github.com / translation-preamble wording.
- pages left on the English template fallback: 120 → 12 (the remaining 12 are stale pages the sync no longer regenerates, not extraction failures).
- all descriptions ≤ 160 chars, one at 38 (whole overview paragraph shorter than the floor).
The docs-side result ships as a separate sync PR (Comfy-Org/docs) so script and generated pages stay reviewable apart.

_{🔄 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/188 **Author:** [@lin-bot23](https://github.com/lin-bot23) **Created:** 10/17/2026 **Status:** ✅ Merged **Merged:** 10/18/2026 **Merged by:** [@comfyui-wiki](https://github.com/comfyui-wiki) **Base:** `main` ← **Head:** `fix/desc-disclaimer-ja` --- ### 📝 Commits (3) - [`9911c53`](https://github.com/Comfy-Org/embedded-docs/commit/9911c53c39c0c1abce19960a770f9b7a357e1cdc) fix: skip plain-paragraph AI disclaimers when building descriptions - [`74add05`](https://github.com/Comfy-Org/embedded-docs/commit/74add0519b2c276463cbea0c70d27c48de497adb) fix: read the overview from an overview H2 when the page has no lead paragraph - [`d5c3848`](https://github.com/Comfy-Org/embedded-docs/commit/d5c3848c820863cbc455eabe7a7ad48e934e4648) fix: require AI wording in the English disclaimer matcher ### 📊 Changes **2 files changed** (+132 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `docs-generation/scripts/sync_to_comfy_docs.py` (+59 -7) 📝 `docs-generation/tests/test_sync_helpers.py` (+73 -0) </details> ### 📄 Description ## Summary Two defects in the description extractor made localized node pages ship meta descriptions that describe nothing. **1. Plain-paragraph AI disclaimers became the description.** `get_description_from_content()` only skipped the disclaimer when the page wrote it as a blockquote (`> ...`). The ja and zh pages ship it as a plain opening paragraph, and the line also carries the `[GitHubで編集する](...)` / `[在GitHub上编辑](...)` link. On the docs site 27 ja pages and 1 zh page used the disclaimer as their whole description: - `ja/built-in-nodes/CaseConverter.mdx` → `このドキュメントはAIによって生成されました。` - `ja/built-in-nodes/StringConcatenate.mdx` → `このドキュメントはAI生成です。` After #187 grew short descriptions to the 40-char floor these got worse, because the growth pulled the "edit on GitHub" URL into the 160-char window. **2. Pages whose overview sits under an H2 fell back to the English template.** 30 nodes write the overview as `## 概述` / `## 概要` / `## 개요` / `## Overview` instead of a lead paragraph under the H1. The extractor broke on the first H2, produced an empty description, and `build_frontmatter()` filled in `"Complete documentation for the X node in ComfyUI. Learn its inputs, outputs, parameters and usage."` on zh/ja/ko pages (120 pages). ## Changes - `docs-generation/scripts/sync_to_comfy_docs.py` - `DISCLAIMER_LINE` matches the disclaimer opening in every shipped language (`This document was generated…`, `此文档由 AI…`, `このドキュメントは AI…`, `이 문서는 AI…`), blockquote or plain paragraph. The old blockquote check is kept as `_BLOCKQUOTE_AI_DISCLAIMER` for pages that use the quote form with other wording. - `_is_overview_heading()` / `_OVERVIEW_HEADINGS`: before any prose has been collected, an overview-style H2 is entered instead of ending the scan; a later `## Overview` therefore cannot hijack text that already started under the H1. Doubled-hash headings (`## ## 概述`, a known translation artifact) are normalised. - Prose that merely mentions AI-generated content is untouched (`This node applies AI-generated textures…`). - `docs-generation/tests/test_sync_helpers.py`: 8 regression tests covering the ja/zh plain-paragraph disclaimer (with the GitHub link), the English wording `This document is AI-generated` / `was generated with AI`, ordinary prose like `This document was written to explain the node` (kept, not skipped), a legitimate AI-generated mention, overview H2s in zh/ja/ko/en, the doubled-hash heading, and `## Inputs` first (template fallback remains correct there). ## Verification - `python3 -m unittest tests.test_sync_helpers` → 40 tests OK. - Full `sync_to_comfy_docs.py --mode all` against a docs worktree: - 0 of 853 generated descriptions contain `AI-generated` / `AI生成` / `AI에` / `AIによって` / `github.com` / translation-preamble wording. - pages left on the English template fallback: 120 → 12 (the remaining 12 are stale pages the sync no longer regenerates, not extraction failures). - all descriptions ≤ 160 chars, one at 38 (whole overview paragraph shorter than the floor). - The docs-side result ships as a separate sync PR (Comfy-Org/docs) so script and generated pages stay reviewable apart. --- <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:24 +00:00