Систему подготовки документации?

Система подготовки документации

Ищу мощный инструмент подготовки документации.

Требования:
Общие требования
  1. Исходный код документации в виде простого текса (markdown, atlassian wiki (aka jira), etc.)
  2. Исходный код в виде файлов и папок
  3. Локальный сервер для командной строки для генерации html по требованию (просмотр результатов)
  4. Плагин для IDEA, Eclipse, NetBeans с подсказками и подсветкой синтаксиса.
  5. Инструменты должны работать под Windows, MacOS и Linux (можно Python, Java или что-то еще)


Поддержка форматирования
  1. Форматирование параграфов и заголовков
  2. Специальные блоки документа (цитаты, врезки)
  3. Форматирование списков
  4. Форматирование вложенных списков
  5. Форматирование текста: подчеркивание, курсив, полужирный
  6. Форматирование текста: ключевые слова, имена файлов
  7. Форматирование таблиц
  8. Подписи к таблицам
  9. Повторение заголовков при переносе на другую страницу
  10. Форматирование блоков исходного кода с подсветкой синтаксиса
  11. Подписи к блокам исходного кода
  12. Форматирование математических выражений
  13. Форматирование химических формул
  14. Нумерация формул и выражений
  15. Форматирование диаграмм
  16. Форматирование диаграмм с данными подключаемыми из внешнего файла
  17. Подписи к диаграммам
  18. Форматирование внедренных изображений
  19. Простые манипуляции с внедренными изображениями (масштаб, обрезка)
  20. Подписи к внедренным изображениям
  21. Поддержка ссылок (на документ, на параграф, на изображение и т.п.)
  22. Поддержка сносок
  23. Поддержка внедренных комментариев

Генераторы содержимого
  1. Генерация оглавлений
  2. Генерация алфавитных указателей
  3. Генерация списков таблиц
  4. Генерация списков блоков исходного кода
  5. Генерация списков диаграмм
  6. Генерация списков изображений
  7. Генерация списков внешних ссылок

Обработка ошибок
  1. Восстановление от синтаксических ошибок
  2. Генерация списка синтаксических и других ошибок
  3. Валидатор для командной строки

Выходные данные
  1. Генерация HTML(XHTML)
  2. Генерация PDF
  3. Генерация XML (для автоматизации или преобразований в другие форматы)



Не все требования являются жизненно необходимыми.

Способ использования такой системы
  • Пишу/правлю исходный текст документации в файлах
  • Результаты проверяю браузером. Специальный http-сервер генерирует html при каждом обновлении страницы. Stdout от вышеупомянутого сервера показывает лог работы
  • Чтобы сгенерировать документацию использую ant doc-html, ant doc-pdf или что-то подобное.
  • Исходный текст документации записывается в git (или другую VCS)
  • Чтобы распечатывать на бумагу генерирую pdf и распечатываю нужные страницы.
  • Для поиска использую grep -r -i 'колобок' doc-src, или алфавитный указатель.
  • Continues Integration сервер генерирует и хранит pdf и html документацию


На данный момент использую pandoc.


Кто-нибудь знает рабочую связку инструментов для такой работы?
  • Вопрос задан
  • 4217 просмотров
Пригласить эксперта
Ответы на вопрос 2
@iroln
Sphinx не подойдёт? С помощью этой системы пишется документация для множества Open Source проектов, например, для Python. Сам использую давно в реальных проектах.
Ответ написан
Ваш ответ на вопрос

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

Войти через центр авторизации
Похожие вопросы