Создание документации для большого (ish) многоязычного API

Question

Я являюсь автором довольно крупной (и растущей) структуры. Он в основном предоставляет JavaScript API, но также имеет общедоступные API в Ruby и растущий сегмент CoffeeScript. (CoffeeScript, в конечном счете, будет охватывать большую часть проекта, но всегда будет значительное присутствие чистого JavaScript.)

До сих пор я документировал JavaScript с помощью PDoc и Ruby с RDoc. Хотя у меня нет проблем с RDoc, к сожалению, PDoc стареет, обладает высоким уровнем обслуживания и требует огромного набора текста, который кажется излишним беспорядком. Кроме того, переход большей части кода на CoffeeScript делает PDoc гораздо менее полезным, чем это было.

Example of the project's current documentation

Я экспериментировал с Rocco в местном отделении, и она работает лучше, чем я ожидал. Что действительно приятно, так это то, что он работает с всем моим кодом, от Ruby to Coffee до JS. Приятно видеть всю документацию в одном месте. Приятно видеть исходный код рядом с документацией, и это очень ясно показывает, какой именно сегмент кода на самом деле делает.

Однако, я немного обеспокоен общей структурой. Docco/Rocco отлично подходит для нишевых проектов с очень небольшим количеством публичных API, но его стиль «весь-проект» поражает меня как обоюдоострый меч. Хотя это очень информативно, нужно по вертикали прокручивать файлы без оглавления (не говоря уже о том, какой файл в первую очередь нужно!) Кажется, что это действительно затруднит на самом деле найти что угодно. Кроме того, шаблон по умолчанию требовал некоторого взлома, потому что список файлов был слишком длинным для отображения. Не огромная сделка, а раздражение, и намек на то, что этот проект может оказаться вне Лиги Рокко.

Я сейчас рассматриваю CoffeeDoc. Судя по этому примеру, это кажется многообещающим, но, конечно, это кофе-центрист, который возвращает меня к запуску 3 отдельных инструментов документации: RDoc, CoffeeDoc и - что? JSDoc?

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

Итак, я думаю, мой вопрос: какой инструмент вы используете или предлагаете? На каком языке (ах) он поддерживает? Легко ли просматривать, читать и на самом деле найти иглу в стоге сена, которая является вашим проектом? Я даже подумываю о том, чтобы на данный момент использовать собственный инструмент, за исключением того, что я не могу поверить, что никто другой не столкнулся с такой проблемой (и я не хочу тратить время, если мне это не нужно).

Answer 1

Sphinx напрямую поддерживает javascript. Документация Ruby и CoffeeScript поддерживается через расширения (https://bitbucket.org/birkenfeld/sphinx-contrib/).

С сайта:

следующие функции присутствуют, работают хорошо, и можно увидеть «в действии» в документации Python:

• Выходные форматы: HTML (включая Windows, HTML Help), LaTeX (для печатных версий PDF), страницы руководства, простой текст
• Обширные перекрестные ссылки: семантическая разметка и автоматические ссылки для функций, классов, цитат, терминов глоссария и аналогичных частей информации
• Иерархическая структура: легко определение дерева документа, с помощью автоматических ссылок на братьев и сестер, родителей и детей
• Автоматические индексы: общий индекс, а также модуль индекса
• обработки Код: автоматическая подсветка с использованием Pygments Highlighter
• Extensions: автоматическое тестирование фрагменты кода, включение docstrings из модулей Python (API docs) и другие