Comments 17
Ну вы молодцы и зайки, если статья была написана для похвалы, то держите, вот она. А нам-то с этого какой профит? Попробовать где-то можно?
Возьмите карту до 120 дней без процентов(возьмём с вас по дружбе, не много).
Еще положите денег. Получите доход (без процентов).
И тогда Вам покажем скриншоты.
Добрый день! Мы поделились опытом, который можно применить для решения практических задач. Надеемся, что информация полезна всем, кто разрабатывает подобные системы или находится на этапе выбора инструмента документирования. Также рассказали о новом продукте в линейке Platform V. Если продукт вас заинтересовал, мы можем провести демо. Оставьте, пожалуйста, заявку на нашем сайте https://platformv.sbertech.ru/products/prikladnye-produkty/get-docs.
здорово что спички на кдпв уложены поперек а не вдоль, значит их еще и обрезать пришлось
Занимаюсь сейчас примерно тем же самым, но пока в начале пути :) Поэтому пару вопросов
Sphinx из коробки не умеет генерить docx, что вы для этого используете? Делали свои шаблоны для публикации docx документов?
Не совсем понял, зачем комбинируете rst и md? Rst побогаче будет. Md обычно берут, если нужно попроще.
Как работаете со сложными таблицами? У нас аналитики любят в конфлюенсе использовать вложенные таблицы - как вы их "парсили"? Я пробовал просто экспортировать в ворд, а потом пандоком в рст, в целом получается неплохо, но приходится дорабатывать напильником.
Для генерации DOCX мы используем Pandoc, набор lua- и python-фильтров для поддержки разметки MyST Markdown.
MyST выбрали, потому что у MD ниже порог входа, чем у RST. Можно писать на обычном MD и только при необходимости начать использовать дополнительные директивы. В компаниях, где большое число пользователей с разным бэкграундом, выгоднее выбирать простую разметку. Чем легче разметка, тем проще начать писать. А у нас еще часто сжатые сроки на написание документации. Простота инструмента дает возможность эти сроки выдержать. MyST дает полную поддержку директив RST, поэтому в любой момент можно перейти на расширенный синтаксис и начать пользоваться дополнительными директивами.
Сложные таблицы оформляются либо директивой flat-table (https://return42.github.io/linuxdoc/linuxdoc-howto/table-markup.html#flat-table). Также можно делать таблицы в HTML-формате, но мы не рекомендуем этого делать.
Ответ на главный вопрос почему из заглавия: потому что "выгодно". Почему это "выгодно" осталось загадкой :-)
Здравствуйте, спасибо за то что поделились опытом. Скажите пожалуйста, будет ли этот инструмент доступен для внешних пользователей? Также интересно, как именно вы используете Vale для русского языка. Вы просто ищете русскоязычные слова как последовательность символов, или же у вас есть свои наборы более высокоуровневых правил?
Здравствуйте, продукт коммерческий. Мы можем провести демо и подробно рассказать о функциональности. Оставьте, пожалуйста, заявку на нашем сайте https://platformv.sbertech.ru/products/prikladnye-produkty/get-docs.
Валидатор в составе продукта включает набор из нескольких отдельных специализированных валидаторов. В Vale-валидаторе используем регулярные выражения для правил, которые хорошо формализуются. В основном это правила из нашего руководства по стилю, но не только. Также есть набор валидаторов собственной разработки, некоторые из которых используют ИИ. Мы планировали посвятить этой теме отдельную статью, которую опубликуем ближе к осени.
А этот некий движок получается создаёт просто сайтик с конкретной версией доки, а если хочется как у postgres? В самой доке содержится куча версией между которыми можно переключиться.
Наш сборщик формирует сайт документации на все продукты. Генерируется каталог со списком всех продуктов, и для каждого продукта отдельный раздел, где можно выбрать документацию нужной версии продукта.
Сайт выглядит вот так https://client.sbertech.ru/docs/public/
Спасибо, а скачать и протестировать-то где?
Победить хаос в документации: почему мы создали свой продукт для Docs-as-a-Code