Asciidoc и doc-as-code

Сохраняю для истории фрагмент обсуждения в телеге:

Q: Хочу попробовать цеттель для написания учебного пособия по электронике + немного кодинга, в идеале — чтобы цеттель был такой базой знаний, из которой по кускам можно было бы (полу)автоматически собирать документацию к проектам (а если и шаблонный код то вообще ух!)

A: Если хочется писать именно в Obsidian, то нужно ориентироваться на Markdown. В этом случае можно попробовать следующий путь:
markdown → Pandoc → любой другой формат

Можно попробовать вместо Obsidian использовать другой редактор, например VSCode, плагином к нему подключить удобную разметку и тем самым исключить pandoc как промежуточный этап.

Если речь идет о учебном пособии, то я бы всё же ориентировался на более богатые чем markdown языки разметки, и менее упоротые чем LaTeX. Например RST или Asciidoc

Мы в компании используем именно Asciidoc для создания документации. Выбирали осмысленно и не сразу. Поэтому лично я рекомендую его.
В Asciidoc уже писали учебники. Примером служит руководство по гиту - ProGit (GitHub - progit/progit2: Pro Git 2nd Edition) полностью написанное в asciidoc.

Так же существует генератор статических сайтов - Antora, с помощью которой можно отобразить книгу в виде красивого web-портала. Её плюс в том, что она может собирать кусочки документов не только из разных репозиториев, но и из разных веток этих репозиториев. Поэтому у такой документации сохраняется не только преемственность информации, но и появляется контроль версий и даже возможность работы с разными языками.

Q: По личному опыту чем asciidoc богаче маркдауна?

A: Сам язык разметки богаче. Предоставляет множество возможностей, которые в markdown можно сделать только костылями.

Например нормальные, человеческие таблицы с форматированием, нумерация разделов, подписи под иллюстрациями. Вставки управляющих команд, например о запрещении переноса куска текста на следующую страницу.

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


Направление называется “doc-as-code”, документация-как-код. Если хочется пообсуждать, то можно создать тему на форуме с таким заголовком. Но только вопрос придумайте. Точнее конечную цель которую хотите достичь. (Возможно для вашей цели все эти инструменты могут быть избыточными)

5 симпатий

Я это сюда притащил, потому что не знал про Antora, мне было бы интересно посмотреть, как они версионируют документы (на досуге сам почитаю), ну и мне вообще жалко бросать в телеге больше двух абзацев связного текста.

Раз автор постов у нас зарегистрирован, то авторство возвращаю где взял.

Вот как Федора генерирует документацию с помощью аскидока. Они тоже используют Антору. Это портал с их документацией:
https://docs.fedoraproject.org/en-US/docs/

Там видно и использование версий и использование разных языков

А. Я себе вообразил почему-то подход, ориентированный на ханки. Или на конкретные коммиты.

Это было бы удобно для личного использования и literate конфигов как git blame на стероидах.

Список каналов в Telegram, связанный с DocAsCode и DocOps:

Любители AsciiDoctor

DocOps-сообщество

DocOps

Foliant

2 симпатии