Навигация: как работают сгенерированные файлы

Для каждой локали четыре навигационных артефакта генерируются из тем этой локали и не пишутся вручную (плюс README.md, который генерируется один раз для эталонной локали, en-gb-oxendict):

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 темы (оглавление его использует).

Сначала запустите python3 tools/localize.py, если меняли что-либо в locales/en-gb-oxendict/, чтобы темы остальных трёх локалей (и порождаемые ими заголовки) были актуальны до того, как их прочтёт gen_nav.py; см. 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, чтобы убедиться, что всё согласовано.