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?

Answer 1

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.

Answer 2

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.