Sto usando yard per generare la mia documentazione per le app Rails da un file rdoc. Esistono generatori di documentazione AngularJS, ma come potrebbero essere collegati per generare un documento coerente per un'app AngularJS + Rails?Come documentare l'app AngularJS + Ruby on Rails?
In questo caso è probabilmente meglio averli separati, e in effetti può avere più senso separarli. Angular sarà destinato esclusivamente ai tuoi clienti, e presumo che tu stia utilizzando Rails come API o forse un altro componente delle funzionalità dell'app. In entrambi i casi, stanno fondamentalmente facendo cose diverse, quindi avrebbe senso averli in diverse sezioni doc.
Se desideri, puoi creare una "pagina di destinazione" per la tua documentazione: un pulsante collega i documenti Angular doc e uno a Rails e ciò risolve la necessità di averli entrambi "in un unico punto". In realtà, trovare un modo per farli coincidere nello stesso sistema probabilmente non vale la pena, e potrebbe effettivamente essere un'esperienza utente peggiore.
Come indicato nella risposta precedente, sarebbe opportuno utilizzare due strumenti diversi e collegarli tra loro.
Vorrei iniziare con qualcosa come Apipie o solo rdoc per documentare la roba rubino. Inoltre vorrei cercare un buon generatore di documentazione js. This article confronta quattro diversi generatori, mentre 'Docco' sembra avere una porta rubino con quella che si chiama 'Rocco', che potrebbe essere anche in grado di generare documentazioni per entrambi, ruby e js. D'altra parte, JSDoc ti consente di integrare pagine personalizzate nei tuoi documenti (qui puoi inserire un link al generatore di apipie).
In generale probabilmente andrei per il documento API rails e ho alcune convenzioni per commentare il tuo codice angolare, in quanto il materiale angolare probabilmente non ha API accessibile da un'altra parte del tuo sistema e quindi necessita solo di una documentazione interna .
Ma perché la tua documentazione dovrebbe essere "coerente"? È necessaria la Documentazione API per la controparte di Rails e la documentazione di origine per Angular. Mi sto perdendo qualcosa? – EugZol
Sarebbe utile avere riferimenti a modelli e metodi di guide pertinenti nei documenti angolari e viceversa. – helcim
Non è questo il principio di accoppiamento libero? Dovresti avere il minor numero possibile di dipendenze, la tua app angolare dovrebbe fare affidamento su _http apis_ non direttamente sull'app Rails, credo –