Система подготовки документации
Ищу мощный инструмент подготовки документации.
Требования:
Общие требования
- Исходный код документации в виде простого текса (markdown, atlassian wiki (aka jira), etc.)
- Исходный код в виде файлов и папок
- Локальный сервер для командной строки для генерации html по требованию (просмотр результатов)
- Плагин для IDEA, Eclipse, NetBeans с подсказками и подсветкой синтаксиса.
- Инструменты должны работать под Windows, MacOS и Linux (можно Python, Java или что-то еще)
Поддержка форматирования
- Форматирование параграфов и заголовков
- Специальные блоки документа (цитаты, врезки)
- Форматирование списков
- Форматирование вложенных списков
- Форматирование текста: подчеркивание, курсив, полужирный
- Форматирование текста: ключевые слова, имена файлов
- Форматирование таблиц
- Подписи к таблицам
- Повторение заголовков при переносе на другую страницу
- Форматирование блоков исходного кода с подсветкой синтаксиса
- Подписи к блокам исходного кода
- Форматирование математических выражений
- Форматирование химических формул
- Нумерация формул и выражений
- Форматирование диаграмм
- Форматирование диаграмм с данными подключаемыми из внешнего файла
- Подписи к диаграммам
- Форматирование внедренных изображений
- Простые манипуляции с внедренными изображениями (масштаб, обрезка)
- Подписи к внедренным изображениям
- Поддержка ссылок (на документ, на параграф, на изображение и т.п.)
- Поддержка сносок
- Поддержка внедренных комментариев
Генераторы содержимого
- Генерация оглавлений
- Генерация алфавитных указателей
- Генерация списков таблиц
- Генерация списков блоков исходного кода
- Генерация списков диаграмм
- Генерация списков изображений
- Генерация списков внешних ссылок
Обработка ошибок
- Восстановление от синтаксических ошибок
- Генерация списка синтаксических и других ошибок
- Валидатор для командной строки
Выходные данные
- Генерация HTML(XHTML)
- Генерация PDF
- Генерация XML (для автоматизации или преобразований в другие форматы)
Не все требования являются жизненно необходимыми.
Способ использования такой системы
- Пишу/правлю исходный текст документации в файлах
- Результаты проверяю браузером. Специальный http-сервер генерирует html при каждом обновлении страницы. Stdout от вышеупомянутого сервера показывает лог работы
- Чтобы сгенерировать документацию использую
ant doc-html, ant doc-pdf или что-то подобное.
- Исходный текст документации записывается в git (или другую VCS)
- Чтобы распечатывать на бумагу генерирую pdf и распечатываю нужные страницы.
- Для поиска использую
grep -r -i 'колобок' doc-src, или алфавитный указатель.
- Continues Integration сервер генерирует и хранит pdf и html документацию
На данный момент использую pandoc.
Кто-нибудь знает рабочую связку инструментов для такой работы?
Простой