Project Documentation

[kingcody]

It has come to my attention that there is a strong need for documentation of the generated code. While the code itself in many places is commented, I do understand that it may be difficult for some to follow the code flow and thus the layout of the project.

Over the past few days I've been working with several documentation generators, namely: JSDoc, Dgeni, and Doxx. While I know that JSDoc is a very popular tool, I find it fails to demonstrate the layout of the server side code very well. The main reason being is that it seems to be geared more towards OOP instead of the looser, more modular structure used in this project.

I think that Doxx has some real potential to be used for documenting the sever side code for the project. I've been working with some custom templates and I think it works fairly well already. As far as the client code goes, I've definitely spent less time in that department but, I think Dgeni will work well for that.

Any other thoughts?

[DaftMonk]

I don't have a lot of experience with documentation generators besides JSDoc, so I'll just see what other people have to say. But I would definitely agree that we need to to work on adding documentation.

[kingcody]

@DaftMonk do you have a preference on doc presentation? I'm currently working with a Jade template that gets compiled for each file (see Doxx Example) so you end up with a folder structure of html files that resembles the server folder structure. Doxx uses visionmedia/dox to parse out the doc symbols (aka atoms) into a json structure for each file. I mainly like the flexibility of that setup over JSDoc's.

I'm wondering though, if we were to go with something like Dox(x), where would you like to include the documentation section? Also should we use a generated project as the base of the doc, perhaps incorporated into the demo site? I ask because it would factor into what we use for a docs template. ie: flat html or angular driven.

edit

[andrewstuart]

I'm working on a branch right now using grunt-ngdocs as an option in the initial generator. It's already got all the configuration set up for client side and to livereload the docs and regenerate them on code changes, which works nicely as you have your own documentation alongside your site and both livereloading on changes. I'm working on going through the code and documenting in ngdocs format so that there is some nice filled documentation right off the bat with the generator, and all generated code will be documented with ngdocs.

I just pushed it to the ngdocs branch, so you can check it out there.

After having one tiny issue with grunt-ngdocs and the example/file directives that I'm sure was just me missing something (documentation on all these documentation tools is ironically sparse), I looked into what Angular is currently using, which is dgeni, developed by them.

It looks poised to do really powerful and clean document generation for any type of annotation (through providers, DI, and great configuration) but it's not been super friendly to me thus far. Still a young project from what I can tell.

[kingcody]

@andrewstuart thats awesome, I'm really glad to see others working on this as well! As for ngdocs, I have not heard of that one yet, I'll definitely check out that branch. I've been focusing on the server code documentation more so, but I'd definitely be interested in helping out with your ngdocs/dgeni endeavors. Just let me know if there's anything I can do :)

[kingcody]

Also, you bring up a really good point I might add. I've been working under the assumption that docs generation would be in the (fullstack) generator, but baking it right into the generated project sound like a really neat idea :+1:

[andrewstuart]

I thought it was funny to see the issue today. I also just started thinking about docs and working on this a few days ago.

It's something I did on the last project at work, and it was crazy invaluable having my own service, controller, app, etc. documentation formatted very similarly to the angular docs and livereloaded as I went. It made the effort to document my code seem much, much more valuable because of the instant feedback.

I tend to think dgeni is probably the ideal solution for both sides, as it seems the most flexibe and it's clearly already working for the ngdocs specification, which is used by the angular team itself and I think a really clean, powerful syntax.

My only concern with dgeni is the amount of time I spent banging my head against it last night with little effort. My guess is I'll have to dissect how the angular project is configuring it in order to better understand how best to use it.

[kingcody]

@andrewstuart are you suggesting dgeni for server code documentation (as well)?

[andrewstuart]

I'm probably not in a good position to recommend it, since I haven't actually gotten it to work aside from the pre-made dgeni-example repo. However, it does seem like an ideal solution to generate a really nice documentation site with a section for both the client and server code.

I definitely plan on playing with it more to see how easy that would be, and trying to think of generator users as well who may want to modify how it works.

Have you had any success getting dgeni to work?

[kingcody]

I have not tried to be honest. I will however see what I can do as far as scaffolding it up for a project. I'll let you know how it goes ;)

[andrewstuart]

Here's a quick screenshot of what grunt-ngdocs generates.

Custom styles, images, and scripts can all be loaded as well to customize the site more. Example directives are also available that work similarly to the examples on the angular site. Source tabs, and of course the two rendered together as a working demo.

[kingcody]

I checked out the ngdoc branch, it works well I must say. Also, I took a stab at using grunt-dgeni but I wasn't able to have any success. I think I'll look using dgeni directly and see where that gets me. Were you able to generate any form of docs with dgeni?

[andrewstuart]

Unfortunately, not yet. I've been trying to look more into how Angular has it configured so I can figure it out more. Progress might be a bit slower during the week, though. I'm trying to find a worthwhile way to integrate it into my current projects so I have a good excuse to hack on it at work.

[andrewstuart]

I finally got it working in a very rudimentary form, meaning no base site. Just bare html generation. I do think it's super powerful but I don't know that I like the spirit of the generated content out of the box, since it's all pre-generated html.

My guess is the Angular team went that direction instead of using an angular-driven site just for SEO, essentially.

My thoughts were that it would be really cool to have an angular-driven documentation site, and possibly even store JSON generated from the comments in mongodb, in the spirit of the generator.

It could easily start with the static site since we're kind of given that out of the box and then move to something more dynamic and thick-client as we figure out dgeni. Dgeni seems MVC enough that it should be relatively simple to make it spit out JSON instead of HTML.

What are your thoughts on generated static HTML vs something a little more angularized and API-ified?

[andrewstuart]

Here's my super basic working example, if you're interested.

[kingcody]

generated static HTML vs something a little more angularized

I've been wondering that myself for the past week. I personally am leaning towards "angularized" as that would be more consistent with what other devs here are currently working in and possibly more conducive to contributions. However I will say that I have a bad habit of opting for cutting edge and disregarding backwards compatibility, so it'd probably be good if others weighed in on this as well :smile:

[andrewstuart]

Well, let's pretend we go that direction. Here are my thoughts. Grandiose, as usual.

Event: Code files change (dev mode only, i.e. not dist target)

1. Dgeni parses only those files (newer:dgeni)
2. We connects to default dev database in Mongo, clear out all doc data for the relevant files, then add the new doc data.
3. Using socket.io, we notify all doc site listeners of the model changes, and they re-sync their models.
4. Update documentation on the browser without even livereloading. [5.] Output static html, just because we can? Pro: viewable without grunt serve.

[kingcody]

With respect to 5 (if we do choose), I'd suggest we instead output markdown. That way the docs can be viewed on github and such. Thoughts?

[andrewstuart]

Ah, good call. Markdown would definitely be awesome, and probably pretty easy.

Maybe it could be an option in the generator, where you can select multiple output types?

[andrewstuart]

I've gotten to the point where I can get data out of documentation (using a processor that runs after all ngdocs' processors) and into Mongodb. Now I just have to grok a little more what kind of data I'm going to get back, and what to store.

Again, assuming we do go that way, I have two ways I'm trying to choose between on getting data into mongo. The first would be having full API endpoints just like we generate, but conditionally loaded based on NODE_ENV. Then the dgeni processor can make API calls over http.

The second way would include the conditional api endpoints, but reuse the schemas and load them locally in the processor so that it interacts directly with mongoose and avoids http calls. Definitely faster and more direct, but maybe missing out on some stuff we could do via http for no matter which way the documentation changes. Mongoose middleware might take care of us there, though.

Any thoughts there?

[pihomeserver]

Hi, Does that mean that for now we can use dgeni for doc generation ? I would like to generate my project documentation and i do not have Mongodb. Not sure how to integrate that in the Gruntfile.js ...