В Ruby есть несколько хороших генераторов документов, таких как Yard, rDoc, даже Glyph. Дело в том, что Sphinx делает веб-сайты, PDF, epub, LaTex и т. Д. Все это делается в реструктурированном тексте.
Есть ли альтернатива этому в мире Ruby? Может комбинация программ? Было бы еще лучше, если бы я мог использовать и Markdown.
Начиная с версии 1.0, в Sphinx существует концепция «доменов», которые представляют собой способы разметки сущностей кода (таких как вызовы методов, объекты, функции и т. Д.) На языках, отличных от Python и / или C.
Существует рубиновый домен, так что вы можете просто использовать сам Sphinx. Единственное, чего вам не хватало (я думаю), так это способности Sphinx автоматически создавать документацию из исходного кода с помощью autodoc, которое работает специально с кодом Python.
Если вы хотите использовать Markdown, вы можете проверить JDoc, очень простую документацию на основе Ruby. framework, который позволяет использовать широко поддерживаемую разметку и помещать ее в систему контроля версий. Он позволяет редактировать документацию в выбранном текстовом редакторе и поддерживает:
Он генерирует статический HTML, поэтому итоговую документацию легко разместить и она не сильно влияет на нагрузку на ваш сервер.
Чтобы увидеть это в действии, посетите wpmvc.org.
Еще пара вариантов - использовать Middleman, генератор статических сайтов, принимающий в качестве входных данных либо Kramdown, либо Markdown.
Существуют также фреймворки, разработанные специально для технической документации, использующей Middleman (оба из которых находятся на GitHub), включая lord / slate и pnerger / dpslate (последний является форком первого и предоставляет некоторые улучшения, которые не подходили для вытягивания) . Формат Slate предоставляет формат документации, который включает многие функции Sphinx с некоторыми дополнительными улучшениями. Он имеет трехпанельный вид документа, который включает автоматически сгенерированное оглавление, основное центральное тело, а затем панель с образцом кода справа. Как и в Sphinx, пример кода имеет подсветку синтаксиса.
