Ich verwende Yard, um meine Dokumentation für Rails-Apps aus einer Rdoc-Datei zu generieren. Es gibt AngularJS-Dokumentationsgeneratoren, aber wie können sie verbunden werden, um ein zusammenhängendes Dokument für eine AngularJS + Rails-App zu generieren?Wie dokumentiert man die AngularJS + Ruby on Rails App?
In diesem Fall ist es wahrscheinlich in Ordnung, sie getrennt zu haben, und in der Tat könnte es sinnvoller sein, sie getrennt zu haben. Angular wird ausschließlich für Ihre clientseitigen Sachen verwendet, und ich nehme an, dass Sie Rails dann als API oder vielleicht als einen anderen Teil der Funktionalität der App verwenden. So oder so, sie machen grundsätzlich verschiedene Dinge, deshalb wäre es sinnvoll, sie in verschiedenen Abteilungen zu haben.
Sie könnten eine "Zielseite" für Ihre Dokumentation erstellen, wenn Sie möchten: eine Schaltfläche verweist auf Angular-Dokumente und eine auf Rails-Dokumente, und das würde die Notwendigkeit beseitigen, beide an einem Ort zu haben. Es ist jedoch wahrscheinlich nicht die Mühe wert, einen Weg zu finden, sie im selben System zu überlappen, und es könnte sogar eine schlechtere Benutzererfahrung sein.
Wie die vorherige Antwort sagte, wäre es gut, zwei verschiedene Werkzeuge zu verwenden und sie miteinander zu verbinden.
Ich würde mit etwas wie Apipie oder einfach rdoc beginnen, um die Rubin-Zeug zu dokumentieren. Zusätzlich würde ich nach einem guten js Dokumentationsgenerator suchen. This article vergleicht vier verschiedene Generatoren, während 'Docco' einen Ruby-Port zu haben scheint, der 'Rocco' genannt wird, der sogar Dokumentationen für Ruby und Js generieren kann. JSDoc ermöglicht Ihnen andererseits, benutzerdefinierte Seiten in Ihre Dokumente zu integrieren (hier könnten Sie einen Link zum Apipie-Generator platzieren).
Im Allgemeinen würde ich wahrscheinlich für die Rails-API doc gehen und einige Konventionen für die Kommentierung Ihres eckigen Codes haben, da das eckige Zeug wahrscheinlich keine API hat, auf die ein anderer Teil Ihres Systems zugreifen kann und daher nur eine interne Dokumentation benötigt .
Aber warum sollte Ihre Dokumentation "kohärent" sein? Sie benötigen die API-Dokumentation für Ihr Rails-Gegenstück und die Quellendokumentation für Angular. Fehle ich etwas? – EugZol
Es wäre nützlich, Verweise auf relevante Schienenmodelle und -methoden in den eckigen Dokumenten zu haben und umgekehrt. – helcim
Stört das nicht das Prinzip der losen Kupplung? Sie sollten so wenig Abhängigkeiten wie möglich haben, Ihre eckige App sollte sich auf _http apis_ nicht direkt auf die Rails-App verlassen. Ich glaube –