Skip to content

feat(automation): scripts/sync_listings.py を拡張して『読み進め方ガイド』を動的化 #39

@watanabe-kohei-jp

Description

@watanabe-kohei-jp

背景

PR #36 (feat(automation): auto-sync listings from NN-slug/index.html) で、README の ## 何が読めるか 章テーブルおよび sitemap.xml / llms.txt / index.html の各章 listing が、scripts/sync_listings.py により 各章 NN-slug/index.html の meta を真実源として自動同期 される仕組みが整った。

一方、PR #35 で追加された ## 読み進め方(推奨ルート) セクション(ルート A/B/C)は依然として章ファイル名がハードコードされており、章の追加・リネーム・削除のたびに README を手で直す必要がある。

旧 Issue #37 では別系統の data/reading-routes.json + build.py 拡張案を計画したが、PR #36sync_listings.py 方針と真実源が分裂するため撤回した(Issue #37 のクローズコメント参照)。本 Issue はその後継として、sync_listings.py の仕組みに乗る形 で読み進めガイドを動的化する。

目的

## 読み進め方(推奨ルート) セクション(ルート A/B/C)を、章ファイルの変化に追従できる構造に変える。sync_listings.py の既存パターン(AUTOGEN マーカー + --check / --write)に統合する。

スコープ

in scope

  • ## 読み進め方(推奨ルート) セクションのルート A/B/C 部分を AUTOGEN 区間化
  • ルート定義の正本ファイル(例: data/reading-routes.json)を新設
    • ルート定義(id / label / duration_min / audience / goal / chapters[] / extras[])のみ
    • 章メタ(title / slides)は sync_listings.py が既に index.html から抽出している ものを再利用
  • scripts/sync_listings.py にルート再生成ロジックを追加
  • 既存 --check / --write モードに統合(CI / bot は既存ワークフローを再利用)

out of scope

  • ### 読み方のスタイル(3 パターン) セクション — 章非依存なので静的のまま
  • ### どのルートでも共通の前提 — 章非依存
  • 章メタを各章ディレクトリ側に分散する案 — 既存方針(index.html 抽出)に従う
  • 所要時間表記の「読む / 手を動かす」分離 — 別 Issue 候補(Codex レビュー指摘 _archive ディレクトリを削除 #3

設計方針(叩き台)

  • ルート定義は JSON(YAML だと依存追加が必要、sync_listings.py は標準ライブラリのみ前提)
  • マーカー形式は既存と統一: <!-- listings:auto:reading-routes:start --> / :end -->
  • 章 ID は sync_listings.pyfind_lectures()(または同等関数)の戻り値 と突合し、未宣言・実在しない章は --check で fail
  • ルート note 内に {slides} プレースホルダを許可し、章のスライド数(既に index.html から抽出済み)で埋める

詳細設計は Plan モードで詰める。

受け入れ条件

  • data/reading-routes.json(仮)を編集 → python scripts/sync_listings.py --write で README の該当区間が更新される
  • JSON 内の章 dir 参照が実在しない/実在するのに未宣言の場合、--check が exit 1
  • 既存の章テーブル AUTOGEN(PR feat(automation): auto-sync listings from NN-slug/index.html #36)と整合性が崩れない
  • CI(sync-listings-check.yml)で drift を検出可能
  • main の bot(sync-listings-bot.yml)が再生成して auto-commit する

関連

Metadata

Metadata

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions