Using ngdocs for automated documentation

[0x-r4bbit]

Hey guys, I was wondering if you're interested in using ngdocs as documentation generator, since it provides the sugar for angular specific things like directives, filters and services.

II used the same for the angular-translate project (http://pascalprecht.github.io/angular-translate)

So, if you're interested, please lemme know, I'd happily help out on this one :)

[nateabele]

Yes, please. I'll take a look at angular-translate to get an idea for what is required, in the meantime, please feel free to take the lead on this.

[0x-r4bbit]

@nateabele alright, awesome.

[timkindberg]

That would be awesome, considering you've already used it. I tried getting into it a couple times and ran out of time. Thanks @PascalPrecht!

[nateabele]

@PascalPrecht I took a look at angular-translate. Clearly I have more reading to do about how ngdocs works. 😄 In the meantime, if you have any tasks to delegate in order to make this happen, feel free to write up a checklist here and I'll take care of them as I have time.

[timkindberg]

@PascalPrecht if you could even just get it set up so it was properly working in grunt and exporting the docs correctly, etc. I'm more than happy to fill it in with the content. We could essentially move everything from our wiki over to the docs right? Except then it wouldn't be as easily editable by users, so I'd have to think if I would want to do it. One singular location for docs would be nice though.

[0x-r4bbit]

@timkindberg Hi Tim! Okay I would just start with a proposal on setting this up. Regarding the contents, yea, we could actually just take the stuff that is already in the wiki. With the module I used for angular-translate, you can specify different "parts" of your docs. Which means you can have api docs, a developer guide (which is where the wiki stuff would land) and there's also a section for tutorials :)

I'd say we first of all have to prepare the source code with proper api documentation. I would take care of that, since I'm not deep enough into the ui-router development, but would love to! Once this is done, generating a nice looking documentation from it is very easy. After that I'd set everything up for a proper developer guide and move the stuff from the wiki over.

Oh and last but not least, editing docs wouldn't be that hard for users, since we can link them to the corresponding ngdoc files, where they just have to make the changes they'd also do in the wiki :)

It's a win-win :)

[douglasduteil]

@PascalPrecht Great ! I look forward to see that.
It'll be an occasion for me to see how set it up. I would pimp the angular-ui-docs with it.

[0x-r4bbit]

@douglasduteil By the way, what about the angular-ui-docs project anyway?

[douglasduteil]

Oh Angular UI Docs. It's made to help building docs and dist. But I'm alone in this fight... I end up making a monster... I defiantly have to come back to it to make it useful.

The original goal was having a common build system that you can get from bower to make TravisCI build and auto publish the doc/demos on the gh-pages branch.
It's currently running on UI.Codemirror, UI.Ace, UI.Map and UI.Utils

Then I was thinking that it can build, tag and publish on specific branches to make the recuperation of sub component parts easier through bower (inspired by what @ProLoser said back in the days bower/bower#405)

+ git repo
  + master (src) branch // build directory is ignored
    - tag: src1.0.x
    - tag: src1.1.x
  + gh-pages (doc) branch
  + bower (build) branch // build directory is committed
    - tag: v1.0.x
    - tag: v1.1.x
  + bower-subcomponent (like angular-ui-event) branch
    - tag: ui-event-1.0.x
    - tag: ui-event-1.1.x

It's still work in progress...

[timkindberg]

It's a win-win :)

Sound great! Let me know if/how I can help when the time comes.

[timkindberg]

Hey there's actually a ng-docs branch in the ui-router repo that jeme had started, maybe a good place to start??

[0x-r4bbit]

@timkindberg I'll have a look at this branch and keep you posted here :)

[0x-r4bbit]

@timkindberg Progress: http://f.cl.ly/items/3X08220T2V3542042W0T/Screen%20Shot%202013-12-11%20at%2010.49.43%20PM.png

you get the idea.

[nateabele]

🍻

[0x-r4bbit]

@nateabele @timkindberg Here's a PR that keep you guys up to date: #668

[timkindberg]

@PascalPrecht so shiny!

[timkindberg]

I wonder if there is a way to force the order of the modules, cause ui.router.compat is lame at the top.

[0x-r4bbit]

@timkindberg I think we have to then update the grunt-ngdocs module accordingly. Currently it's just alphabetic-ordered I think.

[0x-r4bbit]

@timkindberg but yea, glad you like it!