LINUX.ORG.RU

Генерация документации. В чем писать документацию?

 


1

2

Озаботился тут подготовкой документации. Пишу для себя - чтобы не забыть, но хочу чтобы красиво и эстетично было.

Смотрел Latex - для меня слишком хардкорно и PDF он генерирует слишком скучно, по академически. Кучу научных статей видел в PDF, деланных такой штукой.

Писал на Sphinx - но мне бы хотелось еще чтобы была возможность генерировать PDF (опционально). Стал рыть на эту тему, PDF там делается через Latex, и как-то сложно все. И потом, rst формат как-то не особо по душе.

Делал записки на коленке в markdown. Вот он кулл.

http://www.mkdocs.org/ - сайт генератор, в котором все пишется на markdown.

Короче. Изначально, я хочу чтобы все было в html - красиво, но чтобы была опция загенерироваться в PDF одним файлом - книжкой.

Поделитесь опытом, в чем вы пишите. Может, Sphinx крут, просто я его неправильно раскуриваю?

P.S. Да, с wiki я тоже развлекался.

Нужные чёткие критерии. А так - rst.

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

Изначально было удобно писать в Wordе, в нем и писал, т.е. у меня там все было красиво и продумано, шрифтики, цвета, применялось все стилями, специаольной приблудой генерировался в pdf и заливалось в dropbox чтобы потом свежим взглядом с планшета полистать, ввиде книжки.

Но тогда мне не нужно было документировать куски кода, а просто комманды.

Вот с кодом там проблемы и начались, мне нужна была подстветка синтаксиса (без подсветки код сложно воспринимать), и все это делается через одно место - через вставку объекта ODT.

В итоге я сполз на sphinx, он-то уменл нормально код отображать. И как оказалось вылизать документ до читабельного состояния - еще более муторное дело.

+ с pdf беда. C дополнением rst2pdf файл pdf собриается, но все выглядит вырвиглазно. Например текст почти лежит на блоках кода. В общем там все плохо.

Короче как-то все смутно и неясно. Мне нужно наверстать такой документ, чтобы приятно было в руки брать.

dopedopedope ()

Я делал это в markdown и pandoc, что бы высрать все это в PDF. Удобно - всякие gitlab/github/bitbucket могут ее показывать прям в репозитории. Однако - жопа с таблицами. Я думаю какой-нибудь плагин к emacs который таблички мышкой в тексте позволяет рисовать может это исправить. У нас в компании во всю используется confluence и он мне кажется идеальным - туча всяких макросов, поддержка таблиц, картинок, всего-всего и может потом генерировать pdf-ки для страниц.

DiKeert ★★ ()

Под что дока? Если работа - нужна система типа вики. Если для себя - хз, пиши в md, если надо (скажем дебиан так любит) его легко в html перегнать

Только помни что у md со стандартизацией проблема

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

LaTeX, если документация планируется как отдельный документ (оформление настраивается, от академичности можно избавиться). Если документация по коду — doxygen

XMs ★★★★★ ()

Для обычной документации asciidoc, а для статей с кучей формул таки tex.

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