Задать вопрос

Ведение проектной документации

Есть у нас проект, для которого есть некоторое количество документации — как для пользователей, так и для программистов. Сейчас она хранится в вики, это не очень удобно. Вот чего я хочу:

1. Документация должна вестись в текстовых файлах, чтобы ее можно было загнать под контроль версий.
2. Желательно вики-форматирование.
3. Каждый файл — это раздел. Можно в тексте ставить ссылки на разделы и подразделы.
4. Можно вставлять изображения.
5. Всё это должно уметь генерироваться в PDF или DOC с кликабельным оглавлением, с сохранением в тексте форматирования, ссылок, изображений.
6. Желательна возможность онлайн-просмотра текста на сайте (как в обычных вики-сайтах).

Варианты, которые я вижу:

1. Обычный вики-движок. Умеет всё, кроме генерации единого PDF с поддержкой указанных выше фич. Хотя есть плагины, которые добавляют эту функциональность (по крайней мере, для mediawiki), мне результат их работы не нравится. Например, инструмент создания книг на wikipedia.org генерирует некликабельное оглавление, которое не распознается как оглавление, и ссылки, по которым не видно, что они ссылки. Еще одна проблема вики — работать можно только при наличии интернета. А локальные текстовые файлы я бы мог править, когда захочу.

2. TeX. Не сомневаюсь, что реализуемо всё вышеперечисленное (кроме вики-разметки). Но мне не кажется, что это правильный и простой путь. Красиво отформатировать документ в LaTeX для меня — проблема.

3. Взять консольный вики-парсер и допилить под свои нужды. Например, mwlib, который теоретически умеет делать экспорт в PDF. Но я еще не смотрел, что за PDF он генерирует.

Что посоветуете?
  • Вопрос задан
  • 7366 просмотров
Подписаться 6 Оценить Комментировать
Решения вопроса 1
@Ghostwriter
Sphinx
Разметка в reStructuredText, каждый файл может быть как разделом, так и страницей, автоматическая генерация оглавлений с произвольной глубиной, поиск по всем документам с помощью JavaScript, шаблонизация, API для расширений, генерация в HTML, Windows HTML Help, LaTeX (для PDF), man pages, plain text.

Пример — http://docs.python.org
Ответ написан
Пригласить эксперта
Ответы на вопрос 6
@sniks
unix-админ
sharepoint не подходит?

Sharepoint:
Набор веб-приложений для организации совместной работы
Функциональность для создания порталов
Модуль поиска информации в документах и информационных системах
Функциональность управления рабочими процессами и cистему управления содержимым масштаба предприятия
Модуль создания форм для ввода информации
Функциональность для бизнес-анализа
Ответ написан
Комментировать
sledopit
@sledopit
Можно посмотреть на dokuwiki. Это вики движок, работает не с базой, а с текстовыми файлами.
Возможно, есть плагины и для pdf. Всё остальное там есть.
Ответ написан
@sniks
unix-админ
В гугле нашел еще одно решение.
PM.portal — проектный портал на платформе Microsoft SharePoint.
Ответ написан
Комментировать
buugman
@buugman
Посмотрите в сторону doxygen, там нет вики-форматирования и я не уверен что там есть кликабельное оглавление в pdf, но все остальное там точно присутствует.
Ответ написан
leonid-lapidus
@leonid-lapidus
А мы использовали DITA -ооочень удобно, всё лежало под контролем версий, и как docbook генерит всё, что пожелаете — главное написать xslt (есть несколько готовых из коробки)
Ответ написан
Комментировать
powerman
@powerman
Systems Architect, Senior Go/Perl Linux Developer
Мы используем asciidoc. Ваши пункты 1-5 умеет из коробки, просмотр через веб-сайт делается через тривиальный скрипт (можно взять мой asciidoc.cgi). Вот статья «Использование asciidoc для документирования проекта».
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Похожие вопросы