Как документировать приложение AngularJS + Ruby on Rails?

Ответ 1

В этом случае, вероятно, прекрасно, если бы они были разделены и действительно имели смысл разделить их. Angular предназначен исключительно для ваших клиентских приложений, и я предполагаю, что вы используете Rails в качестве API или, возможно, другой элемент функциональности приложения. В любом случае, они в основном делают разные вещи, поэтому имеет смысл иметь их в разных разделах документа.

Вы можете создать "целевую страницу" для своей документации, если хотите: одна кнопка связывается с документами Angular, а другая - с документами Rails, и это решит необходимость их обоих "в одном месте". Фактически, выяснение способа их перекрытия в одной и той же системе, скорее всего, не стоит усилий, и может быть хуже, чем у пользователей.

Ответ 2

Как было сказано в предыдущем ответе, было бы неплохо использовать два разных инструмента и связать их вместе.

Я бы начал с чего-то вроде Apipie или просто rdoc для документирования материала ruby. Кроме того, я бы поискал хороший генератор документации js. В этой статье сравниваются четыре разных генератора, в то время как "Docco", похоже, имеет рубиновый порт с именем "Рокко", который может быть даже способен генерировать документацию как для ruby, так и для js. JSDoc, с другой стороны, позволяет вам интегрировать пользовательские страницы в свои документы (здесь вы можете поместить ссылку на генератор apipie).

В общем, я бы, скорее всего, просто пошел за docs API rails и имел некоторые соглашения для комментирования вашего кода angular, поскольку материал angular, вероятно, не имеет API, доступного другой части вашей системы и, следовательно, только потребности некоторая внутренняя документация.