kw_docs2knowledge: документація модулів як частина релізу, а не окремий проєкт

Документація модуля майже завжди живе окремо від коду: у README в git, у Confluence, у нотатках у Slack-каналі проєкту. Працює, поки хтось не забуває зробити ре-імпорт у Knowledge після релізу — а рано чи пізно забуває завжди. kw_docs2knowledge прибирає цей ручний крок: модуль читає теку documentation/ кожного встановленого аддона і синхронізує її в Odoo Knowledge (document.page) автоматично, щодня. Стаття для інтеграторів і команд, які впроваджують власні модулі клієнтам і хочуть, щоб документація не відставала від коду без додаткового процесу.

Чому документація модулів "тихо" перестає оновлюватись

Типовий сценарій: на старті проєкту хтось один раз імпортує README модуля в Knowledge, клієнт задоволений — все структуровано, шукається, посилання клікабельні. Далі виходить новий реліз, документація в git оновлюється, а в Knowledge — ні, бо ре-імпорт ніде не автоматизований і не входить у чек-лист релізу. Через кілька місяців Knowledge показує застарілу версію, а актуальна лежить у git, куди клієнтська команда підтримки не заглядає.

Функціонал для імпорту Markdown в Odoo є — це вміє document_page. Складність в іншому: синхронізація лишається ручною дією, яку легко пропустити, і про пропуск ніхто не дізнається, поки клієнт не поскаржиться на застарілу інструкцію.

Що робить kw_docs2knowledge технічно

Модуль реєструє щоденний ir.cron, який виконує document.page.action_d2k_sync_all(). Крон уникає зайвої роботи над модулями, що не змінювались:

1. Cron читає addons_path з конфігурації Odoo і перебирає всі модулі зі state = installed.
2. Для кожного модуля він спершу звіряє версію: якщо вона не змінилась з останньої успішної синхронізації, теку documentation/ навіть не читає.
3. Для модулів, версія яких змінилась, він порівнює sha256 кожного .md файлу з останнім відомим значенням і конвертує лише нові або змінені файли.
4. Markdown він конвертує в санітизований HTML, локальні зображення заливає в ir.attachment і переписує атрибут src на завантажену копію; відносні посилання між .md файлами переписує на посилання між відповідними сторінками бази знань.
5. Сторінки видалених файлів і сторінки модулів, які більше не встановлені, він видаляє автоматично.

Результат: одна папка documentation/ у репозиторії модуля — і єдине джерело правди, з якого Knowledge підтягує актуальний стан без окремого релізного кроку.

Запобіжники, які варто знати перед впровадженням

Два моменти важливі для команд, які плануватимуть впровадження на клієнтських базах.

По-перше, якщо тека documentation/ тимчасово недоступна для читання (проблема з правами доступу, збій монтування, тимчасово відсутній volume) — модуль вважає це проблемою середовища — не ознакою, що документацію видалили. Модуль пропускається на цьому прогоні, а вже імпортовані сторінки лишаються без змін. Це навмисне рішення: середовищна помилка не повинна виглядати як масове видалення контенту клієнта.

По-друге, є явний guardrail на масове видалення: якщо один прогін синхронізації видалив би понад половину вже імпортованих сторінок — фаза видалення переривається, у лог пишеться попередження, зміни не застосовуються. Такий сценарій виникає, наприклад, якщо хтось випадково перейменував або видалив цілу теку documentation/ в кількох модулях одночасно. Щоб продовжити навмисно, є ручна дія "Force full resync" у меню Knowledge base — вона перевстановлює всі сторінки незалежно від версії й checksum. Той самий "Force full resync" використовується і для менш драматичних випадків: коли документацію відредагували без бампу версії модуля (типова ситуація під час розробки) або коли оновився пакет markdown/його розширення і вже згенерований HTML треба перегенерувати.

Конвенція documentation/ у власних модулях

Щоб теку модуля підхопило автоматично, вона має лежати за шляхом <your_module>/documentation/**/*.md. Кілька правил, які варто закласти в шаблон нового модуля одразу:

• скануються тільки .md файли, приховані теки (з крапкою на початку) пропускаються;
• тека стає категорією в Knowledge, її назва гуманізується (підкреслення й дефіси → пробіли, з великої літери), якщо її не перейменували вручну пізніше в Odoo;
• заголовок сторінки береться в такому порядку пріоритету: ключ title у YAML frontmatter, потім перший заголовок # H1, потім гуманізована назва файлу;
• README.md у корені documentation/ імпортується як звичайна сторінка, а не як опис самої категорії — document.page не зберігає власного тіла контенту для категорій;
• зображення за відносним шляхом заливаються автоматично, абсолютні URL (http://, https://, data:) лишаються без змін;
• посилання на інші .md файли всередині дерева переписуються на відповідну сторінку Knowledge; посилання на файл поза documentation/ або на ціль, яку не знайдено, лишається як є, з попередженням у лозі;
• синхронізація не виходить за межі власної теки documentation/ модуля і не йде по symlink;
• контент зберігається без історії редагувань: будь-яка ручна правка сторінки прямо в Knowledge буде перезаписана наступним прогоном. Редагувати потрібно вихідний .md у git.

Залежність — OCA document_page (репозиторій knowledge), плюс python-пакет markdown (pip install markdown, уже в requirements.txt). Встановлюється як звичайний модуль, окремої конфігурації не потребує — крон увімкнено за замовчуванням.

Підсумок

Для команди, яка впроваджує й супроводжує десятки клієнтських Odoo-баз, kw_docs2knowledge знімає один конкретний клас проблем — застарілу документацію в Knowledge, про яку ніхто не згадує, поки клієнт не поскаржиться. Джерело правди лишається там, де воно й має бути — в git, поруч із кодом модуля. Сторінка модуля — kw_docs2knowledge, решта — у каталозі модулів. Якщо потрібна допомога з впровадженням document_page/kw_docs2knowledge на клієнтських базах або з побудовою власної конвенції documentation/ під партнерську лінійку модулів — напишіть нам.