Кому это

Документация в Markdown без доводки

Перенос документации обычно состоит из конвертации HTML, а потом из ещё более долгой уборки того, что конвертер оставил. Именно эта уборка здесь и построена, и замерена: ноль остатков HTML на 512 страницах корпуса и 102 повтора строк меню против 282, 478 и 491 у сравниваемых движков.

Конвертация – не работа

Лёгкая часть переноса – та, на которую все смотрят. Конвертер выдаёт Markdown за несколько секунд, а настоящая работа начинается после: убрать боковое меню, скопированное в каждый файл, переключатель версий, колонку «На этой странице», подвал с юридическими ссылками. На двухстах страницах это не делается ни руками, ни одними регулярками.

Структура тоже не выходит невредимой. Пустые заголовки, оставленные навигационными блоками, создают в оглавлении разделы-призраки, врезки теряют смысл, заборы теряют язык, а таблицы параметров складываются. Импортированная документация вроде бы есть, но перед употреблением её надо перечитать страницу за страницей.

Отдельная потеря – врезки. В исходной документации у них есть тип: примечание, совет, предупреждение, «не делайте так никогда». В Markdown стандартного синтаксиса для них нет, поэтому все они становятся одинаковыми цитатами, и после переноса предупреждение о потере данных выглядит ровно так же, как совет про удобное сочетание клавиш. Восстанавливать тип приходится глазами, по тексту, – на двухстах страницах это отдельная работа, которую никто не закладывает в срок.

Что переносится без потерь

• Заголовки, списки, таблицы, заборы кода и сноски становятся стандартным Markdown
• Метки языка на заборах сохраняются – 73 забора из 156 против 20 и 0 у сравниваемых движков
• Ноль остатков HTML на 512 замеренных страницах
• Панели навигации, переключатели версий и колонки «На этой странице» срезаются, а не конвертируются
• Пустые заголовки – частый след навигационных блоков – удаляются
• Шаблон имени файла и подпапка держат перенесённый набор в порядке
• Ссылки достраиваются до абсолютных, а якоря внутри страницы остаются якорями – #parameters не превращается в чужой адрес
• Колонка «На этой странице» и хлебные крошки уходят как идущие подряд строки-ссылки, а одиночная ссылка в абзаце остаётся

---
title: "pathlib – пути файловой системы в объектном стиле"
source: "https://docs.python.org/ru/3/library/pathlib.html"
extraction: "dom"
---

## Основное использование

```python
from pathlib import Path

for file in Path(".").glob("**/*.md"):
    print(file)
```

> Примечание: класс `Path` сам выбирает реализацию под текущую систему.

Как переносить документацию страницами

Перенос – это не одно действие, а двести одинаковых. Настройка ниже нужна затем, чтобы каждое из них состояло из одного нажатия и не требовало решений.

1. В настройках, в разделе «Куда сохранять», выберите папку назначения на диске и оставьте шаблон имени {title}. Имена файлов должны повторять названия разделов – по ним потом собирается оглавление в репозитории.
2. Переключите «Клик по иконке» на «Положить в папку». На двухстах страницах разница между одним нажатием и тремя – это разница между работой на два дня и работой на неделю.
3. Заведите в разделе «Правила по сайтам» правило на домен документации со своей подпапкой. Если разделов несколько, меняйте подпапку по ходу: одна подпапка на раздел избавляет от разбора кучи в конце.
4. Идите по оглавлению исходной документации сверху вниз и на каждой странице жмите Alt+Shift+M. Краулера здесь нет: двести страниц – это двести нажатий, зато каждая снимается такой, какой её отрисовал браузер, включая внутреннюю документацию за входом.
5. Раз в двадцать страниц открывайте последний файл и смотрите на заборы кода и таблицы. Метки языка стоят там, где их объявила исходная страница: на замеренном корпусе метка пережила клип в 73 заборах из 156 против 20 и 0 у двух сравниваемых движков.
6. После переноса пройдитесь по набору поиском по ](http, чтобы найти ссылки на исходный сайт. Они остались абсолютными намеренно – переписывать их под структуру вашего репозитория расширение не берётся, и это единственный шаг, который придётся делать отдельно.

Готовые настройки для переноса документации

Набор рассчитан на однообразную работу в один заход. Всё, что требует решения на каждой странице, из него убрано заранее.

---
title: "shutil – операции с файлами высокого уровня"
source: "https://docs.python.org/ru/3/library/shutil.html"
extraction: "dom"
---

## shutil.copytree

> Предупреждение: даже высокоуровневые функции копирования не переносят
> все метаданные файла.

| Аргумент | По умолчанию | Что делает |
| --- | --- | --- |
| `symlinks` | `False` | копирует цель ссылки, а не саму ссылку |
| `dirs_exist_ok` | `False` | разрешает писать в существующий каталог |

Три сценария целиком

Двести страниц за два дня

Документация переезжает с закрывающейся платформы, экспорта нет, доступ к базе никто не даст. Вы настраиваете папку, шаблон имени и правило на домен, а дальше идёте по оглавлению сверху вниз, нажимая одну и ту же клавишу.

На выходе двести файлов с одинаковой схемой имён, сохранёнными уровнями заголовков и таблицами параметров. Пустые заголовки, которые оставляют навигационные блоки, удалены – разделов-призраков в оглавлении не появится. Остаётся ручная работа: переписать внутренние ссылки и разобраться, какие врезки были предупреждениями.

Сверка терминов с документацией смежной команды

Вам нужно понять, как соседний отдел называет те же сущности, но их документация живёт за корпоративным входом. Клип снимает страницу, которую браузер отрисовал после вашей авторизации, – внутренние страницы клипаются так же, как публичные.

Двадцать файлов в папке ищутся полнотекстовым поиском, и расхождение в терминах видно за один запрос. Сам текст при этом никуда не уходит: внутренние документы остаются на вашем диске, и их содержимое браузер не покидает.

Черновик своей страницы по чужому руководству

Вы пишете раздел про интеграцию и опираетесь на официальное руководство поставщика. Выделяете нужный кусок с примерами, клипаете выделение – к нему не применяется ни срезка, ни отказ «статьи нет» – и вставляете в черновик.

Заборы приезжают с метками, поэтому подсветка в вашем движке документации включается сразу. Текст при этом не переписан и не пересказан: конвертация структурная, и что из чужого руководства можно использовать, а что нельзя, решаете вы.

Чем это заменяет привычные способы

Перенос делают пятью способами, и выбор между ними – это выбор между масштабом и качеством. Строчка про скрипт честно признаёт, где он сильнее.

Что мешает при переносе

Почему все врезки стали одинаковыми цитатами?

Потому что в Markdown нет стандартного синтаксиса для врезок. Примечание, совет и предупреждение выражаются одним и тем же блоком цитаты: содержимое сохраняется, тип – нет.

Восстанавливать тип придётся по тексту. Если ваш движок документации поддерживает свой синтаксис врезок, самый быстрый путь – пройти набор поиском по первому слову внутри цитаты: «Примечание», «Внимание», «Предупреждение».

Почему у части заборов нет метки языка?

Потому что исходная страница её не объявила. Язык читается из атрибутов и классов на самом блоке кода и на двух родителях выше – угадывать по содержимому расширение не станет. На замеренном корпусе метка пережила клип в 73 заборах из 156, против 20 и 0 у двух сравниваемых движков: это заметно больше, но не все.

Почему внутренние ссылки ведут на старый сайт?

Потому что они достроены до абсолютных – намеренно. Так ссылка из перенесённого файла открывается, а не ломается. Якоря внутри страницы при этом остаются якорями: #parameters не превращается в чужой адрес. Переписать ссылки под структуру репозитория – отдельный шаг, и расширение за него не берётся.

Почему на обзорной странице раздела написано, что статьи нет?

Потому что обзорная страница состоит из ссылок: указатель методов, список компонентов, карта раздела. Когда тела статьи не находится или больше четверти текста приходится на подписи ссылок, расширение отдаёт шапку с адресом. Такие страницы в переносе всё равно обычно пересобирают заново – оглавление проще написать, чем чинить.

Чего он не делает

Он не обходит сайт: одна страница за раз, та, что перед вами, без краулера и пакетной обработки – на документацию в двести страниц придётся двести клипов. Он не скачивает картинки и схемы, они остаются ссылками на исходный сайт. Врезки и предупреждения становятся цитатами, потому что стандартного синтаксиса для них в Markdown нет: содержимое сохраняется, оформление нет. И он не пересобирает ни внутренние ссылки документации, ни её оглавление.

Вопросы