Добавление примеров для Python SDK в api-reference

[vvsh-itsolution]

Здравствуйте, добавили оставшиеся примеры вызовов для Python SDK

[vk-bitrix-doc]

Спасибо за большую работу — 1194 страницы получили рабочую вкладку Python, конфликтов с main нет, кодировка везде UTF-8.

Проверял сборкой: собрал локально base-коммит (8b853d25) и ветку PR через @diplodoc/cli@5.39.8 и сравнил логи сборки и итоговый HTML по всем 1523 изменённым страницам. Ниже то, что различается не в пользу PR.

Блокеры — 4 файла, вёрстка ломается

1. api-reference/crm/leads/custom-form/crm-lead-details-configuration-get.md

Строка 72 — {% list tabs %} не закрыт, единственное новое сообщение сборки:

WARN YFM005 / block-not-closed [Context: "    {% list tabs %}"]

Вместе с {% endlist %} вырезано содержимое после блока PHP CRest (заканчивается на строке 239). В результате:

• в разделе «Примеры кода» не рендерится ни одна вкладка — было 7 в двух блоках (cURL (Webhook), cURL (OAuth), JS (TS), JS (UMD), PHP, BX24.js, PHP CRest);
• удалены разделы ## Обработка ответа, ### Возвращаемые данные, #### Объект section, #### Объект section_element;
• строки 240–244 — осиротевший хвост таблицы: строки || и закрывающий |# без открывающего #|;
• страница усохла с 272 877 до 177 783 символов.

2. api-reference/crm/leads/custom-form/crm-lead-details-configuration-reset.md

То же самое, строка 72 — {% list tabs %} не закрыт, тот же WARN YFM005. Здесь обрезано ещё сильнее: после «Примеры кода» файл заканчивается, удалены ## Обработка ответа, ### Возвращаемые данные, ## Обработка ошибок, ### Возможные коды ошибок и ## Продолжите изучение. Все вкладки примеров тоже не рендерятся. Страница: 251 469 → 142 378 символов.

3. api-reference/calendar/calendar-event/calendar-event-get.md

Первый блок вкладок (строки 52–141) вложенный: маркеры вкладок стоят на отступе 4 пробела, код — на 8. Новая вкладка добавлена без этого отступа, и вместе с ней потерял отступ уже существующий маркер PHP:

• строка 89: - Python на нулевом отступе (нужно - Python, код — на 8 пробелов);
• строка 120: - PHP — раньше было - PHP, отступ снят, а код блока остался на 8 пробелах.

Нулевой отступ закрывает вложенный блок вкладок, поэтому оба маркера выпадают из него наружу. По факту первый блок рендерится как cURL (Webhook) · cURL (OAuth) · BX24.js — вкладка PHP пропала со страницы, а Python в блок так и не попал.

Второй блок вкладок (146–224) оформлен правильно, там всё в порядке.

4. api-reference/calendar/calendar-event/calendar-event-get-nearest.md

Та же причина, одна строка: строка 116, - PHP вместо - PHP в первом блоке вкладок (48–138). Сам Python на строке 86 добавлен корректно. Итог — в первом блоке пропала вкладка PHP.

Регресс подписей вкладок

В main подписи вкладок нормализованы (коммит 02c4d07e): JS (UMD), JS (TS), PHP, PHP CRest, cURL (Webhook), cURL (OAuth), Python. В двух файлах PR возвращает старые варианты:

api-reference/crm/universal/crm-item-add.md

• строка 1532: PHP CRest → PHP (B24PhpSdk). Плюс у маркера отступ 3 пробела вместо 4, а внутри блока код идёт рвано (строка 1534 — 8 пробелов, 1535 — 7);
• строка 2031: PHP CRest → PHP.

api-reference/crm/deals/user-defined-fields/crm-deal-userfield-add.md

• строка 423: BX24.js → JS;
• строка 583: PHP CRest → PHP (B24PhpSdk);
• строка 696: PHP CRest → PHP.

Просьба вернуть подписи из main.

Некритичное

Место вкладки Python в блоке. Единого места нет: примерно в 1144 блоках она после JS (UMD) перед PHP, примерно в 200 — после PHP, примерно в 123 — в самом конце после PHP CRest. Хорошо бы привести к одному варианту (после JS (UMD), как в большинстве).

Python разрывает пару JS (TS) / JS (UMD) — эти две вкладки должны идти подряд:

• api-reference/tasks/tasks-task-list.md, строка 247;
• api-reference/telephony/voximplant/voximplant-statistic-get.md, строка 275.

api-reference/widgets/crm/detail-activity-area.md, строка 53. На странице нет блоков вкладок вообще, и Python-пример добавлен голым фенсом сразу за js-фенсом, без подписи. Получается два безымянных блока кода подряд, читателю не понять, где что. Плюс пример вклинился между js-примером и скриншотом, который его иллюстрировал. Лучше завернуть оба примера в {% list tabs %} с подписями.

Лишние пустые строки. В хвосте многих новых вкладок остаётся вторая пустая строка; на 8 страницах появились тройные пустые строки (calendar-event-get-nearest.md, crm-item-add.md, crm-item-batch-import.md, crm-item-import.md, crm-item-details-configuration-get.md, crm-type-list.md, crm-type-update.md, disk-folder-upload-file.md).

Отдельно, без правок

PR попутно удаляет уже имеющиеся в main примеры на Python на 31 странице — deals (12), leads (13), company/contact custom-form (4), timeline activity (2). Мы не против, но отметьте, пожалуйста, в описании PR, что это сознательное решение, и планируется ли замена: иначе по этим страницам покрытие Python временно уходит в минус.

Проверено и вопросов нет

• Конфликтов с main нет: пересечений по файлам ноль, merge чистый.
• UTF-8 везде, ни BOM, ни CRLF.
• Дублей подписей в одном блоке вкладок нет, пустых python-фенсов нет.
• Отступ 2 пробела у Python на 35 страницах — не проблема: там и соседние вкладки на 2 пробелах, рендерится корректно.

Если поправите 4 файла из блокеров и подписи вкладок — с нашей стороны всё.

[vk-bitrix-doc]

Спасибо за правки — перепроверил тем же способом: собрал локально base-коммит (8b853d25), ветку PR, текущий main и результат слияния PR в main через @diplodoc/cli@5.39.8, сравнил логи сборки и итоговый HTML по всем 1522 изменённым страницам.

Блокеры закрыты, все 4

• api-reference/crm/leads/custom-form/crm-lead-details-configuration-get.md и ...-reset.md — {% endlist %} вернулся, вкладки рендерятся, разделы ## Обработка ответа, ### Возвращаемые данные, ## Обработка ошибок, ## Продолжите изучение на месте, осиротевшего хвоста таблицы нет.
• api-reference/calendar/calendar-event/calendar-event-get.md и calendar-event-get-nearest.md — Python и PHP встали на отступ 4, вкладка PHP вернулась в первый блок.

Подтверждается сборкой: новых сообщений сборки ноль, WARN YFM005 / block-not-closed пропал; усадки HTML больше 3 % нет ни на одной странице.

Закрыто и из «некритичного»: разрыв пары JS (TS) / JS (UMD) — 0 случаев; тройные пустые строки — 0 новых; api-reference/widgets/crm/detail-activity-area.md PR больше не трогает; удалённые ранее примеры на Python восстановлены — ни одна страница не потеряла Python; скелет примеров унифицирован, client: BaseClient убран, во всех 1542 вкладках один и тот же импорт.

По делу: 1196 страниц получают вкладку Python, 1229 новых вкладок. Слияние с текущим main чистое — 105 общих файлов, конфликтов нет, новых предупреждений после слияния тоже нет.

Осталось поправить — 4 файла

1. api-reference/crm/companies/custom-form/crm-company-details-configuration-get.md

Новое, в прошлый раз этого не было: во втором блоке вкладок BX24.js и PHP CRest продублированы — побайтово одинаковые копии. Блок рендерится как 10 вкладок:

cURL (Webhook) · cURL (OAuth) · JS (TS) · JS (UMD) · PHP · BX24.js · PHP CRest · Python · BX24.js · PHP CRest

Строки 365 и 382 — первая пара, строки 426 и 443 — дубль. Вторую пару нужно удалить.

2. api-reference/crm/companies/custom-form/crm-company-details-configuration-reset.md

То же самое: строки 338 и 356 против дубля на 400 и 418.

3. api-reference/crm/deals/user-defined-fields/crm-deal-userfield-add.md

Подписи вкладок из прошлого ревью не поправлены:

• строка 423: BX24.js → JS;
• строка 583: PHP CRest → PHP (B24PhpSdk);
• строка 696: PHP CRest → PHP.

В рендере со страницы пропали вкладка BX24.js и обе PHP CRest.

4. api-reference/crm/universal/crm-item-add.md

Из двух подписей поправлена одна: строка 2028 вернулась к PHP CRest, а строка 1532 всё ещё PHP (B24PhpSdk). Плюс у маркера отступ 3 пробела вместо 4, а внутри блока код идёт рвано — фенс на 8 пробелах, try { на 7, тело на 11.

Нюанс по пунктам 3 и 4. Дело не только в подписи. В main соглашение такое: PHP содержит пример на B24PhpSdk, PHP CRest — пример через crest.php. В этих двух файлах PR меняет их местами — под подписью PHP теперь лежит require_once('crest.php'), а SDK-пример уехал в PHP (B24PhpSdk). Возврат подписей из main заодно чинит и это.

Некритичное, осталось как было

• Место вкладки Python в блоке. Единого места по-прежнему нет: после JS (UMD) — 1068 блоков, после PHP — 165, в конце после PHP CRest — 161, после JS — 62. Хорошо бы привести к одному варианту, после JS (UMD), как в большинстве.
• Строка Пример во вкладке Python. На 227 страницах вкладка Python содержит строку Пример, которой нет у соседних вкладок того же блока — например, api-reference/crm/automated-solution/crm-automated-solution-add.md, api-reference/common/settings/app-option-get.md.
• Правки без содержания. 25 страниц (companies, contacts, quote, imopenlines-session-mode-silent.md) меняются только удалением одной пустой строки между вкладками — Python туда не добавлен, на рендер это не влияет. Похоже на случайный шум в диффе.

Отдельно, без правок

sdk/b24pysdk/index.md — содержательное обновление обзора SDK: .value / .values, модуль b24pysdk.schemas, набор зависимостей signals, параметр secure_log. Это вне заявленного в заголовке api-reference — отметьте, пожалуйста, в описании PR.

Проверено и вопросов нет

• Конфликтов с main нет, merge чистый, новых предупреждений сборки после слияния ноль.
• UTF-8 везде, ни BOM, ни CRLF.
• Пустых python-фенсов нет.
• Потерянных вкладок и усохших страниц, кроме перечисленных 4 файлов, нет.

Если поправите 4 файла из списка — с нашей стороны всё.