Documentation proposal - all directives in README

[prognostikos]

Would you guys accept a pull request where I move documentation/examples for each directive into the README?

[pkozlowski-opensource]

@prognostikos as you can see we've started those efforts on the boostrap directives only recently and we terribly do lack documentation. The trouble is that we didn't figure out (yet) how to organize it. We've learned some good things while working on angular-ui but we also made some mistakes that we would like to avoid. What we have learned the hard way:

• examples need to be synchronized with the released code
• examples on the page should be tested, otherwise it becomes too fragile
• ideally it should be possible to run examples in a jsFiddle / plunk (as on the AngularJS home page).

So, the above is the ideal but given that we've got zero documentation at the moment, any help will be highly appreciated! I just promise that docs will stay in readme forever :-)

Now, to help with the effort here are the jsFiddles / plunks for some of the existing directives:

• modal: http://plnkr.co/edit/WoWWKP?p=preview
• dropdownToggle: http://jsfiddle.net/eX4aH/13/

Accordion and tabs got a bit of documentation next to the code, I can assist with doing a plunk if needed.

So, in short - yes - we need any help we could get with documentation!

[dandoyon]

@pkozlowski-opensource

So, yesterday, I thought I was being clever and wrote a "real-time" jsfiddle poster (using strictly jquery) that worked from the angular-ui homepage. It basically searches the page for some data-* annotations and creates a form to be posted to jsfiddle. Today, as I was testing it, I came to the sober realization that I made an error in judgement. The problem being is that the html code that I was posting to jsfiddle was already transformed.

For example, the below (data-html is annotation i'm looking for in jquery)

            <div data-html class="well">
                        <ng-form name="dateForm">
                            <p><input name="dateField" value="Click Here for Datepicker" ng-model="date" ui-date></p>
                        </ng-form>
                        <p>Selected Date: {{ date }}</p>
                        <p>Formatted Date: {{ date | date: 'mediumDate'}}</p>
                        <p>Selected Month: {{ date.getMonth() }}</p>
                        <div ng-model="date" ui-date></div>
                    </div>

was coming over as

div ng-app="demoApp">
                        <ng-form class="ng-pristine ng-valid" name="dateForm">
                            <p><input id="dp1351443153713" class="ng-pristine ng-valid hasDatepicker" name="dateField" value="Click Here for Datepicker" ng-model="date" ui-date=""></p>
                        </ng-form>
                        <p class="ng-binding">Selected Date: </p>
                        <p class="ng-binding">Formatted Date: </p>
                        <p class="ng-binding">Selected Month: </p>
                        <div id="dp1351443153714" class="ng-pristine ng-valid hasDatepicker" ng-model="date" ui-date=""><div style="display: block;" class="ui-datepicker-inline ui-datepicker ui-widget ui-widget-content ui-helper-clearfix ui-corner-all"><div class="ui-    datepicker-header ui-widget-header ui-helper-clearfix ui-corner-all"><a class="ui-datepicker-prev ui-corner-all" onclick="DP_jQuery_1351443153710.datepicker._adjustDate('#dp1351443153714', -1, 'M');" title="Prev"><span class="ui-icon ui-icon-circle-           triangle-w">Prev</span></a><a class="ui-datepicker-next ui-corner-all" onclick="DP_jQuery_1351443153710.datepicker._adjustDate('#dp1351443153714', +1, 'M');" title="Next"><span class="ui-icon ui-icon-circle-triangle-e">Next</span></a><div      class="ui-datepicker-title"><span class="ui-datepicker-month">October</span>&nbsp;<span class="ui-datepicker-year">2012</span></div></div><table class="ui-datepicker-calendar"><thead><tr><th class="ui-datepicker-week-end"><span title=

            --- truncated ---

as it would be

What I should've been doing was pulling in the "prettyprint" bits, but that would require regex to pull out html/script/style. And that would also mean that the examples would have to be consistent and complete for jsfiddle consumption.

<pre class="prettyprint" ng-non-bindable>

I also put in place a means of generating a button based on an attribute of the section element, thus allowing for a static definition (for jsfiddle, plunkr etc).

<section id="directives-date" data-example-url="http://jsfiddle.net/mXakz/">

in any event, i'm a bit sheepish, i should've figured this out sooner rather than later, but what i did early on was to change all the <script tags to be different so that I didnt (see ext-examples2) have to wait for them to download as i was testing. And renaming the script tags actually made it work pretty better, of course rendering index.html unusable (make sense). Even this way is not 100%

This may have been a complete waste of time, however, it could get others thinking of better ways or help with creating jsfiddles, each fiddle needs testing.

https://github.com/dandoyon/angular-ui.github.com/tree/ext-examples

https://github.com/dandoyon/angular-ui.github.com/tree/ext-examples2 <-- this one could be used for statically generating jsfiddles.

As a side note, jsfiddle has a way of allowing you to add resource urls, there is a bug (as is noted on angularjs fiddles) and I "think" i was actually finding that it was not ordering the resources sequentially which is important otherwise cleaner fiddles could be created.

let me know what you think

--dan

On Oct 26, 2012, at 11:26 AM, Pawel Kozlowski wrote:

@prognostikos as you can see we've started those efforts on the boostrap directives only recently and we terribly do lack documentation. The trouble is that we didn't figure out (yet) how to organize it. We've learned some good things while working on angular-ui but we also made some mistakes that we would like to avoid. What we have learned the hard way:

examples need to be synchronized with the released code
examples on the page should be tested, otherwise it becomes too fragile
ideally it should be possible to run examples in a jsFiddle / plunk (as on the AngularJS home page).
So, the above is the ideal but given that we've got zero documentation at the moment, any help will be highly appreciated! I just promise that docs will stay in readme forever :-)

Now, to help with the effort here are the jsFiddles / plunks for some of the existing directives:

modal: http://plnkr.co/edit/WoWWKP?p=preview
dropdownToggle: http://jsfiddle.net/eX4aH/13/
Accordion and tabs got a bit of documentation next to the code, I can assist with doing a plunk if needed.

So, in short - yes - we need any help we could get with documentation!

—
Reply to this email directly or view it on GitHub.

[pkozlowski-opensource]

Interesting... I was actually thinking more about what is done on the angular.js home page. @dandoyon, have you had a look at https://github.com/angular/angularjs.org/blob/master/js/homepage.js#L136 ?

For me somehow the example should be stored in git in its executable form and then we should generate a page and jsFiddle / plunker from this.

I'm not sure if I'm making myself clear so we can have a chat on gchat / IRC / hangout. I would love to spend more time on this but won't be able in the near future...

[dandoyon]

i'm all too familiar with the angularjs version but it probably wouldn't hurt to revisit it, since things have changed since I worked on it. Originally, it was baked into the build process. It mayn mean restructuring our home page but probably worthwhile in the long run.

I'll revisit and make a proposal

On Oct 28, 2012, at 11:55 AM, Pawel Kozlowski wrote:

Interesting... I was actually thinking more about what is done on the angular.js home page. @dandoyon, have you had a look at https://github.com/angular/angularjs.org/blob/master/js/homepage.js#L136 ?

For me somehow the example should be stored in git in its executable form and then we should generate a page and jsFiddle / plunker from this.

I'm not sure if I'm making myself clear so we can have a chat on gchat / IRC / hangout. I would love to spend more time on this but won't be able in the near future...

—
Reply to this email directly or view it on GitHub.

[petebacondarwin]

Can we point to Plnkrs instead of Fiddles. They are just so much nicer to
work with. There is an API: https://github.com/filearts/plunker
Pete

On 28 October 2012 20:36, Dan Doyon notifications@github.com wrote:

i'm all too familiar with the angularjs version but it probably wouldn't
hurt to revisit it, since things have changed since I worked on it.
Originally, it was baked into the build process. It mayn mean restructuring
our home page but probably worthwhile in the long run.

I'll revisit and make a proposal

On Oct 28, 2012, at 11:55 AM, Pawel Kozlowski wrote:

Interesting... I was actually thinking more about what is done on the
angular.js home page. @dandoyon, have you had a look at
https://github.com/angular/angularjs.org/blob/master/js/homepage.js#L136?

For me somehow the example should be stored in git in its executable
form and then we should generate a page and jsFiddle / plunker from this.

I'm not sure if I'm making myself clear so we can have a chat on gchat /
IRC / hangout. I would love to spend more time on this but won't be able in
the near future...

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/12#issuecomment-9850175.

[dandoyon]

Quickly looking at this, it looks easier to handle over jsfiddles api. Thanks for looking into it Pete. When I have some time, i'll see what's involved and make a proposal.

--dan

On Oct 28, 2012, at 1:44 PM, Pete Bacon Darwin wrote:

Can we point to Plnkrs instead of Fiddles. They are just so much nicer to
work with. There is an API: https://github.com/filearts/plunker
Pete

On 28 October 2012 20:36, Dan Doyon notifications@github.com wrote:

i'm all too familiar with the angularjs version but it probably wouldn't
hurt to revisit it, since things have changed since I worked on it.
Originally, it was baked into the build process. It mayn mean restructuring
our home page but probably worthwhile in the long run.

I'll revisit and make a proposal

On Oct 28, 2012, at 11:55 AM, Pawel Kozlowski wrote:

Interesting... I was actually thinking more about what is done on the
angular.js home page. @dandoyon, have you had a look at
https://github.com/angular/angularjs.org/blob/master/js/homepage.js#L136?

For me somehow the example should be stored in git in its executable
form and then we should generate a page and jsFiddle / plunker from this.

I'm not sure if I'm making myself clear so we can have a chat on gchat /
IRC / hangout. I would love to spend more time on this but won't be able in
the near future...

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/12#issuecomment-9850175.

—
Reply to this email directly or view it on GitHub.

[petebacondarwin]

Geoff, who wrote it, is keen on Angular. I am sure he would help out with
making the API work better for us if we asked!

On 28 October 2012 21:43, Dan Doyon notifications@github.com wrote:

Quickly looking at this, it looks easier to handle over jsfiddles api.
Thanks for looking into it Pete. When I have some time, i'll see what's
involved and make a proposal.

--dan

On Oct 28, 2012, at 1:44 PM, Pete Bacon Darwin wrote:

Can we point to Plnkrs instead of Fiddles. They are just so much nicer
to
work with. There is an API: https://github.com/filearts/plunker
Pete

On 28 October 2012 20:36, Dan Doyon notifications@github.com wrote:

i'm all too familiar with the angularjs version but it probably
wouldn't
hurt to revisit it, since things have changed since I worked on it.
Originally, it was baked into the build process. It mayn mean
restructuring
our home page but probably worthwhile in the long run.

I'll revisit and make a proposal

On Oct 28, 2012, at 11:55 AM, Pawel Kozlowski wrote:

Interesting... I was actually thinking more about what is done on
the
angular.js home page. @dandoyon, have you had a look at

https://github.com/angular/angularjs.org/blob/master/js/homepage.js#L136?

For me somehow the example should be stored in git in its executable
form and then we should generate a page and jsFiddle / plunker from
this.

I'm not sure if I'm making myself clear so we can have a chat on
gchat /
IRC / hangout. I would love to spend more time on this but won't be
able in
the near future...

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHub<
https://github.com/angular-ui/bootstrap/issues/12#issuecomment-9850175>.

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/12#issuecomment-9851099.

[pkozlowski-opensource]

Plunker support was just pushed to the AngularJS, we could try to do sth similar:
angular/angular.js@3c9b39f...090e542

[dandoyon]

cool
On Oct 31, 2012, at 1:08 PM, Pawel Kozlowski wrote:

Plunker support was just pushed to the AngularJS, we could try to do sth similar:
angular/angular.js@3c9b39f...090e542

—
Reply to this email directly or view it on GitHub.

[pkozlowski-opensource]

Closing this one as we've got now infrastructure for adding documentation and all the existing directives are documented thnx to awesome work of @ajoslin.

Still I'm going to open another issue with a list of things that we can improve in the demo site. BTW, the WIP version is on-line here: http://ci.angularjs.org/job/angularui-bootstrap/ws/dist/index.html