Как разработать техническую документацию, которая точно будет работать. Часть 2. DocOps в действии

[yyqwerty]

При использовании DocOps много доп. возможностей и удобный интерфейс к ним предоставляет foliant.

[agladilin]

Да, интересный продукт из разряда glue software))). Радует обилием возможностей, но не радует генерацией PDF через Pandoc на основе LaTeX-шаблона… хотя можно и через md-to-pdf. Однозначно можно рекомендовать для знакомства.

[Kinddog]

ничего себе "легкое знакомство"...

полноценный подход к описанию задачи и ее решению, давно такого не встречал, спасибо большое за интересный материал ))

[agladilin]

Спасибо). Буду рад, если пригодится.

[atshaman]

А JB'шный Getting started - Writerside | JetBrains Marketplace writerside не смотрели?

[agladilin]

Этот продукт я ждал). Не знал, что он вышел. Обязательно посмотрю, спасибо).

[atshaman]

Вышел, пользуюсь, нравится - но генерация PDF вида "сделай сам pandoc'ом из html'ки", что надо иметь в виду "на берегу".

[agladilin]

Как, впрочем, и у Yandex Flavored Markdown. От таких гигантов ждешь каких-то комплексных решений, а получается очередной генератор статики, в которых, собственно, недостатка и так нет).

[atshaman]

Ну, у меня задачи "готовить документацию в отчуждаемом виде" нет - мне паттерны jb\yandex'а несколько ближе. Надо чтобы:

а) рабочая документация велась в репе с кодом\проектом

б) для работы с документацией использовался тот же тулинг, что и для работы с проектом

в) чтобы результат выглядел порогово прилично без приложений осмысленных усилий задействованных сторон

В принципе, writerside это обеспечивает. В случае необходимости выгрузить и отправить PDF'ку на согласование - ну, обычно встроенного markdown converter'а IDE хватает - если нет, тут уже боль-страдания-неоправданные-жертвы, на которые я раз в году готов идти ).

[Abobcum]

Подскажите, пожалуйста, генератор адекватный api reference для mkdocs. Сколько не искал - какая-то сырая ерунда. Довольно сложно api описывать руками, когда можешь сгенерить из docstring.

[agladilin]

Едва ли смогу что-то добавить к этому списку. Кроме того, должен признаться, что ни одно из этих решений я не смотрел).

[Abobcum]

Спасибо. Да, я смотрел этот список. К несчастью, самописное решение работает лучше любого планировщик из списка.

[olku]

Из asciidoc делаются красивые пдфки одним кликом.

[ReDev1L]

Если не нужен pdf - https://github.com/withastro/starlight можно разбавлять любым JS, красивые компоненты mdx из коробки