How to document AngularJS + Ruby on Rails app? [closed]

Question

I'm using yard to generate my documentation for Rails apps from an rdoc file. There are AngularJS documentation generators, but how could they be connected to generate one coherent document for an AngularJS + Rails app?

Koblenz

But why your documentation should be 'coherent'? You need API Documentation for your Rails counterpart, and source documentation for Angular. Am I missing something? – Barricade

It would be useful to have references to pertinent rails models and methods in the angular docs and vice versa. – Koblenz

Isn't this breaking the loose coupling principle? You should have as least dependencies as possible, your angular app should rely on http apis not directly to the Rails app I believe – Vedavedalia

Perhaps, but maybe it's plain wrong to apply it blindly everywhere? If I'm writing an app consisting of Angular frontend and Rails backend it would be more useful for me to have a system (or at least a precise set of rules) which helps to document both with least effort. I guess it might be beneficial for potential authors of other backends or frontends to have the very coupling of both documented in a nice way. – Koblenz

Looking back at this question after two years it seems my approach gets some justification, although I wasn't able to define what I want precisely. It seems what I was after was something like swagger and it's not just a problem of documentation but rather one of design principles. – Koblenz

Answer 1

In this case it is probably fine to have them separated, and indeed may make more sense to have them separated. Angular is going to be solely for your client-side stuff, and I'm assuming you're then using Rails as an API or perhaps a different piece of the app's functionality. Either way, they are fundamentally doing different things, so it would make sense to have them in different doc sections.

You could create a "landing page" for your documentation if you'd like: one button links to Angular docs and one to Rails docs, and that would solve the need to have them both "in one place". Actually figuring out a way to make them overlap in the same system is likely not worth the effort though, and may actually be a worse user experience.

Wing

It is fine from the point of view of future maintainers of both frontend and backend. However it would be significantly more productive to have a single source of documentation in projects which start as small one-developer ventures. – Koblenz

Answer 2

As the previous answer stated, it would be good to use two different tools and link them together.

I would start with something like Apipie or just rdoc to document the ruby stuff. Additionally I would search for a good js documentation generator. This article compares a four different generators, while 'Docco' seems to have a ruby port with that is called 'Rocco', that may be even able to generate documentations for both, ruby and js. JSDoc on the other hand enables you to integrate custom pages into your docs (here you could place a link to the apipie generator).

In general I would probably just go for the rails API doc and have some conventions for commenting your angular code, as the angular stuff probably has no API that is accessible by another part of your system and therefore only needs some internal documentation.

Hairbrush