LINUX.ORG.RU

В чем делать документацию?


3

6

Это не про ту, что в коде, а про ту, что рядом: проектную, описывающую архитектуру, требования, тестовые планы, и пользовательскую

Что хотелось бы?

1) Удобный для редактирования язык разметки

2) merge, diff и прочие прелести контроля версий.

3) Синхронизация с кодом (правка кода и документации в одном комите)

4) Красивый html и сносный pdf

5) Возможность писать структурированные документы. Например: текст требования, процедура проверки, отметка о реализации.

doc/odf вообще не вариант.

latex дает красивый pdf, позволяет писать структурированные файлы, но html убогий.

docbook можно допинать до хорошего html'а и обучить через xslt кушать структурированные файлы, но редактировать совсем не удобно.

mediawiki/dokuwiki дает удобный язык разметки, красивый html, сносный pdf, но не синхронизируется с кодом. Со структурированными документами вроде бы плохо.

Есть еще варианты?

★★

То есть про markdown ты не в курсе, или он сразу отпадает про причине своей простоты? Куча проектов на том же гитхабе использует этот формат для документации и вики (есть в том числе сложные иерархические руководства с перекрёстными ссылками и генерацией оглавления/references).

Про конвертацию HTML, PDF можно не думать, пока есть такие инструменты как pandoc (конвертация с любого формата в любой). Есть куча генераторов markdown -> HTML -> что угодно.

mtk ()
Ответ на: комментарий от mtk

То есть про markdown ты не в курсе, или он сразу отпадает про причине своей простоты?

Слышал, не пользовался, на ум не пришло. А что поверх него для структурированных документов? Вроде таких:

<req name="check_password" status="ok">
    Программа должна проверять пароль на сложность 
    <test_case>Задать пароль из 5 символов</testcase>
    <test_case>Задать пароль в одном регистре</testcase>
    ...
</req>

Куча проектов на том же гитхабе использует этот формат для документации и вики (есть в том числе сложные иерархические руководства с перекрёстными ссылками и генерацией оглавления/references).

Ссылкой на какой-нибудь не поделитесь?

Про конвертацию HTML, PDF можно не думать, пока есть такие инструменты как pandoc (конвертация с любого формата в любой).

Фантастика какая-то.

ival ★★ ()
Последнее исправление: ival (всего исправлений: 1)

проектную, описывающую архитектуру, требования, тестовые планы, и пользовательскую

вы будете смеятся, НО, это форматы ms-word и OO :-) может кроме тестовых планов может быть.

MKuznetsov ★★★★★ ()

Ого, давно интересует тот же вопрос. Подписался.

Apple-ch ★★ ()
Последнее исправление: Apple-ch (всего исправлений: 1)
Ответ на: комментарий от ival

А что поверх него для структурированных документов?

Наблюдаю эпидемию XMLя неокортекса. Документация - для читателя, а он при любой обработке прочтёт что-то типа:

= Требования

== сложность пароля

программа должна ...

=== тесты

1. задать ...
2. задать ...

т.ч. более навороченная структура не нужна.

DonkeyHot ★★★★★ ()

почему odf - не вариант? У него есть свой diff, а с помощью некоторой утилитки (odt2txt, кажется) можно прикрутить его к СКВ. Помнится, я так делал (не для себя) и всё работало нормально

Sahas ★★★★★ ()

но html убогий

Ну так понятное дело: html не рассчитан на верстку текстов! Но на худой конец сойдет latex2html.

Eddy_Em ☆☆☆☆☆ ()

org-mode. Как раз plain text, удобная разметка, и, конечно же структурирование. Плюс куча поддерживаемый форматов для экспорта.

nowhere ()

Я рекомендую sphinx (http://sphinx-doc.org/).

Простой но фичастый текстовый формат.

Есть поддержка структурированной разметки + расширения своими директивами.

Нормальная поддержка ссылок.

Нормальный вывод в html, приемлемый в pdf.

dmitry_vk ★★★ ()
Ответ на: комментарий от tailgunner

Я, конечно, догадываюсь, что это не имеет отношения к representational state transfer, но что-то ничего другого не гуглится.

Ссылочку бы.

Apple-ch ★★ ()
Ответ на: комментарий от Sahas

почему odf - не вариант?

1) odf - никак не структурированная разметка.

2) съезжающие стили, много ручного форматирования

У него есть свой diff, а с помощью некоторой утилитки (odt2txt, кажется) можно прикрутить его к СКВ.

diff есть, а вот merge - нет.

dmitry_vk ★★★ ()
Ответ на: комментарий от Sahas

почему odf - не вариант? У него есть свой diff, а с помощью некоторой утилитки (odt2txt, кажется) можно прикрутить его к СКВ. Помнится, я так делал (не для себя) и всё работало нормально

google подсказал ссылку, но все равно что-то не то. Нету там удобного языка разметки :)

ival ★★ ()
Ответ на: комментарий от tailgunner

ReST

есть какие-то объективные причины для предпочтения reST, например markdown'у? или просто потому что питон?

Stil ★★★★★ ()
Ответ на: комментарий от Stil

есть какие-то объективные причины для предпочтения reST, например markdown'у?

Наличие таки-спецификации, которой нет у md. Есть десяток разных диалектов md.

Расширяемость reST собственными директивами.

dmitry_vk ★★★ ()
Ответ на: комментарий от ugoday

А это точно задача документации?

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

ival ★★ ()
Ответ на: комментарий от Stil

есть какие-то объективные причины для предпочтения reST, например markdown'у?

У меня - нет. Просто это первый из текстовых языков разметки, который мне попался на глаза.

tailgunner ★★★★★ ()
Последнее исправление: tailgunner (всего исправлений: 1)

restructured text, markdown, textile - чо хошь

overmind88 ★★★★★ ()
Ответ на: комментарий от ival

есть толковые свободные системы управления требованиями? А с какого масштаба ими нужно начитать пользоваться?

Для масштаба есть bugzilla, launchpad

А для списка задач мне и issue в github'е хватает.

monk ★★★★★ ()
Ответ на: комментарий от ugoday

Судя по описанию тебе нужно что-то типа ланчпада. А это совсем-совсем далеко от документации.

Нет. Интересует именно документация. Требования, из-за крохотных масштабов, предполагается вести без спецсофта, вручную, на уровне документации.

ival ★★ ()
Ответ на: комментарий от ival

Нету там удобного языка разметки :)

а, сорри, про этот пункт не углядел...

Sahas ★★★★★ ()
Ответ на: комментарий от ival

те (10 штук), что не реализованны

В режиме бровзинга: /TODO<CR> потом n...

В batch, например:

#!/bin/sed -rf
1,/^= +Требования/ d
1,/^== +/ { h ; d ; }
/^= +/,$ d
H
$ g
/^== +/ ! d
/^== +/ {
x
s/\n== +.*$//
/TODO/ ! d
}

DonkeyHot ★★★★★ ()

doxygen — синхронизация с кодом, приемлемый html. Хорош для описания кода, но инструкции, примеры и пр. писать замучаешься. Пригоден для малых и средних проектов.

texinfo — почти как ТеХ, но ориентирован на описание кода. Удобен для всего кроме формул (они есть, но ... тяжко). Хорошо структурирован для большой документации с примерами, рисунками, выделением цветом или начертанием, и т.д. и т.п. Отлично экспортирует в html, info и еще кучу форматов. Хорошо в pdf, но в pdf нет поддержки русского языка (точнее мне не удалось ее настроить).

abalakin ★★ ()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.