Я использую ярлык для создания моей документации для Rails-приложений из файла rdoc. Существуют генераторы документации AngularJS, но как они могут быть связаны для создания одного согласованного документа для приложения AngularJS + Rails?Как документировать приложение AngularJS + Ruby on Rails?
В этом случае, вероятно, прекрасно, если бы они были разделены, и в самом деле может иметь смысл разделить их. Угловой будет исключительно для ваших клиентских вещей, и я предполагаю, что вы используете Rails в качестве API или, возможно, другую часть функциональности приложения. В любом случае, они принципиально делают разные вещи, поэтому было бы целесообразно иметь их в разных разделах док-станции.
Вы можете создать «целевую страницу» для своей документации, если хотите: одна кнопка связывается с документами «Угловая» и одна - с документами Rails, и это решит необходимость иметь их «в одном месте». Фактически, выяснение способа сделать их перекрытием в одной и той же системе, вероятно, не стоит усилий, хотя может и быть хуже, чем у пользователей.
Как было сказано в предыдущем ответе, было бы полезно использовать два разных инструмента и связать их вместе.
Я бы начал с чего-то вроде Apipie или просто rdoc для документирования рубинового материала. Кроме того, я бы поискал хороший генератор документации js. This article сравнивает четыре разных генератора, в то время как «Docco», похоже, имеет рубиновый порт с так называемым «Rocco», который может даже иметь возможность генерировать документацию как для ruby, так и для js. JSDoc, с другой стороны, позволяет вам интегрировать пользовательские страницы в свои документы (здесь вы можете поместить ссылку на генератор apipie).
В общем, я бы, скорее всего, просто поработал над API-интерфейсом rails API и получил некоторые условные обозначения для комментирования вашего углового кода, так как угловой материал, вероятно, не имеет API, доступного другой части вашей системы, и поэтому ему нужна только внутренняя документация ,
Но почему ваша документация должна быть «последовательной»? Вам нужна документация по API для вашей копии Rails и исходная документация для Angular. Я что-то упускаю? – EugZol
Было бы полезно иметь ссылки на подходящие модели и методы рельсов в угловых документах и наоборот. – helcim
Разве это не нарушает принцип свободной связи? У вас должно быть как можно меньше зависимостей, ваше угловое приложение должно полагаться на _http apis_ не прямо на приложение Rails. Я считаю, что –