ナビゲーション: 生成ファイルの仕組み

ロケールごとに、4つのナビゲーション成果物がそのロケールのトピックから生成され、手では書かれません (加えて、参照ロケールen-gb-oxendict向けに一度だけ生成されるREADME.md)。

• README.md(リポジトリのホームページの目次。参照ロケールのみ)
• locales/<locale>/index.md(公開サイトのホームページ)
• locales/<locale>/front-matter/table-of-contents.md
• locales/<locale>/topics/09-07-index.md(リンク付きの主題索引)

これらは tools/gen_nav.pyが生成します。 次の生成であなたの変更が上書きされるので、手で編集しないでください。

いつ再生成するか

次のいずれかを行うたびに、just nav(またはpython3 tools/gen_nav.py)を実行します。

• トピックを追加、削除、名称変更、または番号振り直しした。
• トピックの# N.M Title見出しを変更した(目次はそれを使います)。

locales/en-gb-oxendict/の下で何かを変更したなら、先にpython3 tools/localize.pyを実行して、gen_nav.pyが読む前に 他の3つのロケールのトピック(とその生成タイトル)を最新にします。 spec/locales.mdを参照してください。

仕組み

各ロケールについて、gen_nav.pyはlocales/<locale>/topics/*.mdの各ファイルを読み、小数番号で並べ替え、部ごとにグループ化し、次を行います。

• 各トピックのH1タイトルから、部ごとの目次を作る。
• それをlocales/<locale>/index.mdとlocales/<locale>/front-matter/table-of-contents.md(参照ロケールのみREADME.mdも)に書く。
• 実質的なトピック(第1部から第8部)を固定のキーワードリストでスキャンし、主題索引をlocales/<locale>/topics/09-07-index.mdに書く。

共有の定型文(導入段落、「この本の読み方」、「横断的なテーマ」、部のタイトル)は、トピックの本文と同じ方法、 つまりtools/localize.pyのロケール関数で現地化されるので、生成ページはどのロケールでも自然に読めます。

部のタイトルは、スクリプトの先頭近くにあるPART_TITLES辞書にあります。ジェネレーターはコロン形式の部見出し (「Part 2: Delivery and Flow Metrics」)を使い、エムダッシュは決して使いません。

手で翻訳したロケールでは、ホームページと目次ページは手で書かれ(翻訳された見出しと各部のN.0導入行)、 tools/gen_translated_nav.pyがそのロケールのトピックのH1タイトルからトピック一覧を更新します。

触れないもの

リポジトリ直下の仕様(spec/index.md、spec/structure.mdとその仲間)は、手書きの信頼できる情報源です。ジェネレーターはこれを書かず、 公開サイトの一部でもありません。構造を変えるなら、spec/structure.mdを自分で更新し、派生ファイルのためにjust navを、 すべてが揃っていることを確かめるためにjust testを実行してください。