Move documentation under individual headings

This commit is contained in:
Misko Hevery 2011-04-29 15:18:27 -07:00 committed by Igor Minar
parent b6bc6c2ddf
commit 11e9572b95
53 changed files with 218 additions and 190 deletions

View file

@ -1,4 +1,3 @@

@workInProgress
@ngdoc overview
@name Tutorial: Step 0
@ -16,7 +15,7 @@
The following sample code is our starting point. It is a static HTML page that displays next to
nothing, but it has everything we need to proceed. You can think of this bit of code as our
prototype template, consisting of basic HTML tags with a pair of angular specific attributes.
prototype template, consisting of basic HTML tags with a pair of angular specific attributes.
__`app/index.html`:__
<pre>

View file

@ -1,20 +1,20 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 1
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial Previous}</td>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-1/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">
{@link https://github.com/angular/angular-phonecat/compare/step-0...step-1 Code Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_02 Next}</td>
</tr>
</table>
Now that we have the basic ingredients in place, let's add some basic information about two cell
phones to our app.
phones to our app.
Note: We will usually include only the new code that we added for each step. In this and
subsequent examples, we will leave out code from the previous step that hasn't changed, for
@ -23,7 +23,7 @@ example:
...
<html xmlns:ng="http://angularjs.org">
...
Let's add the following code to `index.html`:
__`app/index.html`:__
@ -53,18 +53,18 @@ __`app/index.html`:__
## Discussion:
* It's a static web page! We displayed info about two phones! Yay.
* It's a static web page! We displayed info about two phones! Yay.
* For those of you playing along at home on your own web servers, did you switch to Step 1 and
refresh your browsers?
refresh your browsers?
* __{@link tutorial Using Git:}__
* __{@link tutorial Using Git:}__
From your `angular-phonecat` directory, run this command:
git checkout step-1
* __{@link tutorial Using Snapshots:}__
* __{@link tutorial Using Snapshots:}__
From `[install directory]/sandbox`, run this command:
@ -78,11 +78,11 @@ into a dynamic web app.
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial Previous}</td>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-1/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">
{@link https://github.com/angular/angular-phonecat/compare/step-0...step-1 Code Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_02 Next}</td>
</tr>
</table>

View file

@ -1,15 +1,15 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 2
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_01 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-2/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-1...step-2 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_03 Next}</td>
</tr>
</table>
@ -41,7 +41,7 @@ __`app/index.html`:__
</pre>
Our data __Model__ (a short list of phones in object literal notation) is instantiated within our
__Controller__ function (`PhoneListCtrl`):
__Controller__ function (`PhoneListCtrl`):
__`app/js/controllers.js`:__
<pre>
@ -84,7 +84,7 @@ enclosed in curly braces: `{{phone.name}}` and `{{phone.snippet}}`:
* The `ng:repeat="phone in phones"` statement in the `<li>` tag is an angular repeater. It
tells angular to create a `<li>` element for each phone in the phones list, using the first
`<li>` tag as the template.
`<li>` tag as the template.
* The curly braces around `phone.name` and `phone.snippet` are an example of {@link
angular.markup angular markup}. The curly braces are shorthand for the angular directive
@ -97,11 +97,11 @@ enclosed in curly braces: `{{phone.name}}` and `{{phone.snippet}}`:
* __Controller:__ At this point, it doesn't appear as if our controller is doing very much
controlling, but it is playing a crucial role: providing context for our data model so we can
establish data-binding between the model and the view. Note in the following how we connected the
dots between our presentation, data, and logic components:
dots between our presentation, data, and logic components:
* The name of our controller function (in the JavaScript file `controllers.js`) matches the
{@link angular.directive.ng:controller ng:controller} directive in the `<body>` tag
(`PhoneListCtrl`).
(`PhoneListCtrl`).
* We instantiated our data within the scope of our controller function, and our template
binding points are located within the block bounded by the `<body
ng:controller="PhoneListCtrl>` tag.
@ -127,11 +127,11 @@ angular. The test verifies that we have 3 records in the phones array.
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_01 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-2/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-1...step-2 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_03 Next}</td>
</tr>
</table>

View file

@ -1,23 +1,23 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 3
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_02 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-3/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link
https://github.com/angular/angular-phonecat/commit/a03815f8fb00217f5f9c1d3ef83282f79818e706 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_04 Next}</td>
</tr>
</table>
We did a lot of work in laying the foundation of our app in the last step, so now we'll do
something simple, and add full text search. We will also write an end-to-end test, because a good
end-to-end test is a good friend. It stays with your app, keeps an eye on it, and quickly detects
regressions.
regressions.
__`app/index.html`:__
<pre>
@ -72,7 +72,7 @@ following:
keeps the two in sync.
In this example, the data that you type into the input box (named __`query`__) is immediately
available as a filter input in the list repeater (`phone in phones.$filter(`__`query`__`)`).
available as a filter input in the list repeater (`phone in phones.$filter(`__`query`__`)`).
Whenever the data model changes and this change causes the input to the repeater to change, the
repeater will efficiently update the DOM to reflect the current state of the model.
@ -97,12 +97,12 @@ your browser. This end-to-end test shows the following:
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_02 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-3/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link
https://github.com/angular/angular-phonecat/commit/a03815f8fb00217f5f9c1d3ef83282f79818e706 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_04 Next}</td>
</tr>
</table>

View file

@ -1,15 +1,15 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 4
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_03 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-4/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-3...step-4 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_05 Next}</td>
</tr>
</table>
@ -151,11 +151,11 @@ initializes the data model.
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_03 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-4/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-3...step-4 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_05 Next}</td>
</tr>
</table>

View file

@ -1,15 +1,15 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 5
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_04 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-5/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_06 Next}</td>
</tr>
</table>
@ -21,7 +21,7 @@ angular.service.$xhr $xhr} service to make this easy.
The addition of the `$xhr` service to our app gives us the opportunity to talk about {@link
guide.di Dependency Injection} (DI). The use of DI is another cornerstone of the angular
philosophy. DI helps make your web apps well structured, loosely coupled, and ultimately easier to
test.
test.
__`app/js/controllers.js:`__
<pre>
@ -137,11 +137,11 @@ reason, we need to:
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_04 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-5/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-4...step-5
Code Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_06 Next}</td>
</tr>
</table>

View file

@ -1,15 +1,15 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 6
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_05 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-6/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-5...step-6 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_07 Next}</td>
</tr>
</table>
@ -64,14 +64,14 @@ __`app/phones/phones.json`__ (sample snippet):
<pre>
[
{
"age": 4,
"age": 4,
...
"carrier": "T-Mobile",
"id": "motorola-defy-with-motoblur",
"imageUrl": "http://google.com/phone/image/small/640001",
"name": "Motorola DEFY\u2122 with MOTOBLUR\u2122",
"carrier": "T-Mobile",
"id": "motorola-defy-with-motoblur",
"imageUrl": "http://google.com/phone/image/small/640001",
"name": "Motorola DEFY\u2122 with MOTOBLUR\u2122",
"snippet": "Are you ready for everything life throws your way?"
},
},
]
</pre>
@ -93,7 +93,7 @@ __`test/e2e/scenarios.js`__:
{@link angular.markup double-curly brace markup} in the href attribute values. These represent
attribute bindings, and work the same way as the bindings we saw in previous steps.
* Note also the use of the {@link angular.directive.ng:src ng:src} directive in the `<img>` tag.
* Note also the use of the {@link angular.directive.ng:src ng:src} directive in the `<img>` tag.
That directive prevents the browser from treating the angular `{{ exppression }}` markup
literally, as it would do if we tried to use markup in a regular `src` attribute. Use `ng:src` to
keep the browser from eagerly making an extra http request to an invalid location.
@ -103,11 +103,11 @@ views we will implement in the upcoming steps.
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_05 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-6/app Example}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-5...step-6 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_07 Next}</td>
</tr>
</table>

View file

@ -1,23 +1,23 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 7
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_06 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-7/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-6...step-7 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_08 Next}</td>
</tr>
</table>
Our app is slowly growing and becoming more complex. Up until now, the app provided our users with
just one view (the list of all phones), and all of our template code was located in the
`index.html` file. The next step in building our app is the addition of a view that will show
detailed information about each of the devices in our list.
detailed information about each of the devices in our list.
To add the detailed view, we could expand the `index.html` file to contain template code for both
views, but that would get messy very quickly. Instead, we are going to turn the `index.html`
@ -142,13 +142,13 @@ two new View templates:
* __The Controller(s).__ We now have a new root controller (`PhoneCatCtrl`) and two
sub-controllers (`PhoneListCtrl` and `PhoneDetailCtrl`). These inherit the model properties and
behavior from the root controller.
behavior from the root controller.
* __`$route.`__ The root controller's job now is to set up the `$route` configuration:
* When the fragment part of the URL in the browser ends in "/phones", `$route` service
grabs the `phone-list.html` template, compiles it, and links it with a new scope that is
controlled by our `PhoneListCtrl` controller.
controlled by our `PhoneListCtrl` controller.
* When the URL ends in "/phones/:phoneId", `$route` compiles and links the
`phone-detail.html` template as it did with `phone-list.html`. But note the use of the
@ -170,12 +170,12 @@ behavior from the root controller.
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_06 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-7/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-6...step-7 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_08 Next}</td>
</tr>
</table>

View file

@ -1,16 +1,16 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 8
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_07 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-8/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-7...step-8 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_09 Next}</td>
</tr>
</table>
@ -69,20 +69,20 @@ __`app/phones/nexus-s.json`:__ (sample snippet)
<pre>
{
"additionalFeatures": "Contour Display, Near Field Communications (NFC), Three-axis gyroscope,
Anti-fingerprint display coating, Internet Calling support (VoIP/SIP)",
Anti-fingerprint display coating, Internet Calling support (VoIP/SIP)",
"android": {
"os": "Android 2.3",
"os": "Android 2.3",
"ui": "Android"
},
},
...
"images": [
"img/phones/nexus-s.0.jpg",
"img/phones/nexus-s.1.jpg",
"img/phones/nexus-s.2.jpg",
"img/phones/nexus-s.0.jpg",
"img/phones/nexus-s.1.jpg",
"img/phones/nexus-s.2.jpg",
"img/phones/nexus-s.3.jpg"
],
],
"storage": {
"flash": "16384MB",
"flash": "16384MB",
"ram": "512MB"
}
}
@ -137,12 +137,12 @@ spirit to the one we wrote for the `PhoneListCtrl` controller.
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_07 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-8/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-7...step-8 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_09 Next}</td>
</tr>
</table>

View file

@ -1,23 +1,23 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 9
@description
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_08 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-9/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-8...step-9 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_10 Next}</td>
</tr>
</table>
In this step, we have determined that the built-in angular display filters ({@link
angular.filter.number number}, {@link angular.filter.currency currency}, {@link
angular.filter.date date}, etc.) don't handle what we want to do, so we get to create our own
custom {@link angular.filter filter}.
custom {@link angular.filter filter}.
In the previous step, the details page displayed either "true" or "false" to indicate whether
certain phone features were present or not. Our custom "checkmark" filter replaces those text
@ -25,7 +25,7 @@ strings with glyphs: ✓ for "true", and ✘ for "false".
Our filter code lives in `app/js/filters.js`:
__`app/index.html`:__
__`app/index.html`:__
<pre>
...
<script src="lib/angular/angular.js" ng:autobind></script>
@ -37,7 +37,7 @@ __`app/index.html`:__
In the phone details template, we employ our filter for angular expressions whose values are
"true" or "false"; `{{ [phone_feature] | checkmark }}`:
__`app/partials/phone-detail.html`:__
__`app/partials/phone-detail.html`:__
<pre>
<img ng:src="{{phone.images[0].large}}" class="phone"/>
<h1>{{phone.name}}</h1>
@ -86,23 +86,23 @@ describe('checkmark filter', function() {
* This example shows how easy it is to roll your own filters for displaying data. As explained in
the "Writing your own Filters" section of the {@link angular.filter angular.filter} page, you
simply register your custom filter function on to the `angular.filter` function.
simply register your custom filter function on to the `angular.filter` function.
* In this example, our filter name is "checkmark"; our input is either "true" or "false", and we
return one of two unicode characters we have chosen to represent true or false (`\u2713` and
`\u2718`).
`\u2718`).
* We created a new unit test to verify that our custom filter converts boolean values to unicode
characters.
<table id="tutorial_nav">
<tr>
<td id="previous_step">{@link tutorial.step_00 Previous}</td>
<td id="previous_step">{@link tutorial.step_08 Previous}</td>
<td id="step_result">{@link http://angular.github.com/angular-phonecat/step-9/app Live Demo
}</td>
<td id="tut_home">{@link tutorial Tutorial Home}</td>
<td id="code_diff">{@link https://github.com/angular/angular-phonecat/compare/step-8...step-9 Code
Diff}</td>
<td id="next_step">{@link tutorial.step_00 Next}</td>
<td id="next_step">{@link tutorial.step_10 Next}</td>
</tr>
</table>

View file

@ -1,4 +1,4 @@
@workInProgress
@workInProgress
@ngdoc overview
@name Tutorial: Step 11
@description
@ -15,11 +15,11 @@ Code Diff}</td>
</table>
And so we arrive at the last step of this tutorial. Here we define a custom service that
represents a {@link http://en.wikipedia.org/wiki/Representational_State_Transfer RESTful} client.
represents a {@link http://en.wikipedia.org/wiki/Representational_State_Transfer RESTful} client.
Using this client we can make xhr requests for data in an easier way, without having to deal with
the lower-level {@link angular.service.$xhr $xhr} APIs, HTTP methods and URLs.
__`app/index.html`.__
__`app/index.html`.__
<pre>
...
<script src="js/services.js"></script>

View file

@ -1,57 +0,0 @@
<h1><tt>{{name}}</tt></h1>
{{#workInProgress}}
<fieldset class="workInProgress">
<legend>Work In Progress</legend>
This page is currently being revised. It might be incomplete or contain inaccuracies.
{{{workInProgress.description}}}
</fieldset>
{{/workInProgress}}
{{#deprecated}}
<fieldset class="deprecated">
<legend>Deprecated API</legend>
{{deprecated}}
</fieldset>
{{/deprecated}}
<h2>Description</h2>
{{{description}}}
<h2>Dependencies</h2>
<ul>
{{#requires}}
<li><tt>{{name}}</tt></li>
{{/requires}}
</ul>
{{#method.length}}
<h2>Methods</h2>
<ul>
{{#method}}
<li><tt>{{shortName}}()</tt>: {{{description}}}</li>
{{/method}}
</ul>
{{/method.length}}
{{#property.length}}
<h2>Properties</h2>
<ul>
{{#property}}
<li><tt>{{name}}:{{#type}}{{type}}{{/type}}</tt>{{#description}}: {{{description}}}{{/description}}</li>
{{/property}}
</ul>
{{/property.length}}
{{#example}}
<h2>Example</h2>
{{{exampleDescription}}}
<doc:example>
<doc:source>
{{/example}}
{{{example}}}
{{#example}}
</doc:source>
{{#scenario}}<doc:scenario>{{{scenario}}}</doc:scenario>{{/scenario}}
</doc:example>
{{/example}}

View file

@ -20,7 +20,7 @@ var work = callback.chain(function(){
var writes = callback.chain(function(){
ngdoc.merge(docs);
docs.forEach(function(doc){
writer.output(doc.id + '.html', doc.html(), writes.waitFor());
writer.output(doc.section + '/' + doc.id + '.html', doc.html(), writes.waitFor());
});
var metadata = ngdoc.metadata(docs);
writer.output('docs-keywords.js', ['NG_PAGES=', JSON.stringify(metadata).replace(/{/g, '\n{'), ';'], writes.waitFor());

View file

@ -36,7 +36,6 @@ Doc.METADATA_IGNORE = (function(){
})();
Doc.prototype = {
keywords: function keywords(){
var keywords = {};
@ -57,6 +56,38 @@ Doc.prototype = {
return words.join(' ');
},
/*
* This function is here to act as a huristic based translator from the old style urls to
* the new style which use sections.
*/
sectionHuristic: function (url){
// if we are new styl URL with section/id then just return;
if (url.match(/\//)) return url;
var match = url.match(/(\w+)(\.(.*))?/);
var section = match[1];
var id = match[3] || 'index';
switch(section) {
case 'angular':
section = 'api';
id = 'angular.' + id;
break;
case 'api':
case 'cookbook':
case 'guide':
case 'intro':
case 'tutorial':
break;
default:
id = section + '.' + id;
section = 'intro';
}
var newUrl = section + '/' + (id || 'index');
console.log('WARNING:', 'found old style url', url, 'at', this.file, this.line,
'converting to', newUrl);
return newUrl;
},
markdown: function (text) {
var self = this;
var IS_URL = /^(https?:\/\/|ftps?:\/\/|mailto:|\.|\/)/;
@ -70,7 +101,7 @@ Doc.prototype = {
parts.forEach(function(text, i){
if (text.match(/^<pre>/)) {
text = text.replace(/^<pre>([\s\S]*)<\/pre>/mi, function(_, content){
var clazz = 'brush: js;'
var clazz = 'brush: js;';
if (content.match(/\<\w/)) {
// we are HTML
clazz += ' html-script: true;';
@ -93,7 +124,8 @@ Doc.prototype = {
text = text.replace(/<angular\/>/gm, '<tt>&lt;angular/&gt;</tt>');
text = text.replace(/{@link\s+([^\s}]+)\s*([^}]*?)\s*}/g,
function(_all, url, title){
return '<a href="' + (url.match(IS_URL) ? '' : '#!') + url + '">'
var isFullUrl = url.match(IS_URL);
return '<a href="' + (isFullUrl ? '' + url : '#!' + self.sectionHuristic(url)) + '">'
+ (url.match(IS_ANGULAR) ? '<code>' : '')
+ (title || url).replace(/\n/g, ' ')
+ (url.match(IS_ANGULAR) ? '</code>' : '')
@ -525,6 +557,7 @@ function metadata(docs){
var depth = path.length - 1;
var shortName = path.pop();
words.push({
section: doc.section,
id: doc.id,
name: doc.name,
depth: depth,
@ -538,7 +571,7 @@ function metadata(docs){
}
var KEYWORD_PRIORITY = {
'.started': 1,
'.index': 1,
'.guide': 2,
'.guide.overview': 1,
'.angular': 7,
@ -562,7 +595,7 @@ function keywordSort(a, b){
mangled.push(KEYWORD_PRIORITY[partialName] || 5);
mangled.push(name);
});
return mangled.join('.');
return doc.section + '/' + mangled.join('.');
}
var nameA = mangleName(a);
var nameB = mangleName(b);

View file

@ -9,15 +9,13 @@ var fs = require('fs'),
var NEW_LINE = /\n\r?/;
function collect(callback){
/*
findJsFiles('src', callback.waitMany(function(file) {
//console.log('reading', file, '...');
console.log('reading', file, '...');
findNgDocInJsFile(file, callback.waitMany(function(doc, line) {
callback(doc, file, line);
callback('@section api\n' + doc, file, line);
}));
}));
*/
findNgDocInDir('docs/', callback.waitMany(callback));
findNgDocInDir('docs/content', callback.waitMany(callback));
callback.done();
}
@ -42,11 +40,18 @@ function findNgDocInDir(directory, docNotify) {
fs.readdir(directory, docNotify.waitFor(function(err, files){
if (err) return this.error(err);
files.forEach(function(file){
//console.log('reading', directory + file, '...');
if (!file.match(/tutorial.*\.ngdoc$/)) return;
fs.readFile(directory + file, docNotify.waitFor(function(err, content){
fs.stat(directory + '/' + file, docNotify.waitFor(function(err, stats){
if (err) return this.error(err);
docNotify(content.toString(), directory + file, 1);
if (stats.isFile()) {
console.log('reading', directory + '/' + file, '...');
fs.readFile(directory + '/' + file, docNotify.waitFor(function(err, content){
if (err) return this.error(err);
var section = '@section ' + directory.split('/').pop() + '\n';
docNotify(section + content.toString(), directory + '/' +file, 1);
}));
} else if(stats.isDirectory()) {
findNgDocInDir(directory + '/' + file, docNotify.waitFor(docNotify));
}
}));
});
docNotify.done();

View file

@ -18,6 +18,24 @@ a {
height: 3.5em;
}
#header .navigation {
position: absolute;
text-align: center;
top: 0;
right: 0;
left: 0;
margin: 0;
padding: 0;
}
#header .navigation > li {
display: inline;
padding: 0 .5em;
}
#header .navigation > li.selected {
font-weight: bold;
}
#sidebar,
#main {
position: absolute;
@ -191,12 +209,8 @@ a {
margin-top: 0;
}
#sidebar ul li.level-1.level-angular {
#sidebar ul li.monospace{
font-family: monospace;
font-weight: normal;
font-size: 1em;
margin-top: 0;
margin-bottom: 0;
}
#sidebar ul li.level-1 {
@ -208,17 +222,14 @@ a {
#sidebar ul li.level-2 {
margin-left: 2em;
font-family: monospace;
}
#sidebar ul li.level-3 {
margin-left: 3em;
font-family: monospace;
}
#sidebar ul li.level-4 {
margin-left: 4em;
font-family: monospace;
}

View file

@ -1,8 +1,8 @@
var HAS_HASH = /#/;
DocsController.$inject = ['$location', '$browser', '$window'];
function DocsController($location, $browser, $window) {
this.pages = NG_PAGES;
window.$root = this.$root;
var self = this;
this.$location = $location;
if (!HAS_HASH.test($location.href)) {
@ -11,28 +11,36 @@ function DocsController($location, $browser, $window) {
this.$watch('$location.hashPath', function(hashPath) {
if (hashPath.match(/^!/)) {
this.partialId = hashPath.substring(1);
this.partialTitle = (angular.Array.filter(NG_PAGES, {id:this.partialId})[0]||{}).name;
var parts = hashPath.substring(1).split('/');
self.sectionId = parts[0];
self.partialId = parts[1] || 'index';
self.pages = angular.Array.filter(NG_PAGES, {section:self.sectionId});
self.partialTitle = (angular.Array.filter(self.pages, function(doc){return doc.id == self.partialId;})[0]||{}).name;
}
});
this.getUrl = function(page){
return '#!' + page.id;
return '#!' + page.section + '/' + page.id;
};
this.getCurrentPartial = function(){
return './' + this.partialId + '.html';
return './' + this.sectionId + '/' + this.partialId + '.html';
};
this.getClass = function(page) {
var depth = page.depth,
cssClass = 'level-' + depth + (page.name == this.partialId ? ' selected' : '');
if (depth == 1 && page.type !== 'overview') cssClass += ' level-angular';
if (page.section == 'api')
cssClass += ' monospace';
return cssClass;
};
this.selectedSection = function(section) {
return section == self.sectionId ? 'selected' : null;
};
this.afterPartialLoaded = function() {
SyntaxHighlighter.highlight();
};

View file

@ -4,23 +4,36 @@
ng:controller="DocsController">
<head>
<title ng:bind-template="&lt;angular/&gt;: {{partialTitle}}">&lt;angular/&gt;</title>
<meta name="fragment" content="!">
<link rel="stylesheet" href="doc_widgets.css" type="text/css" />
<link rel="stylesheet" href="docs.css" type="text/css"/>
<link rel="stylesheet" href="syntaxhighlighter/shCore.css" type="text/css"/>
<link rel="stylesheet" href="syntaxhighlighter/shThemeDefault.css" type="text/css"/>
<script src="jquery.min.js"></script>
<script src="syntaxhighlighter/shCore.js"></script>
<script src="syntaxhighlighter/shBrushJScript.js"></script>
<script src="syntaxhighlighter/shBrushXml.js"></script>
<script src="../angular.min.js" ng:autobind></script>
<script src="docs.js"></script>
<script src="doc_widgets.js"></script>
<script src="docs-keywords.js"></script>
<script>
/*!
* $script.js v1.3
* https://github.com/ded/script.js
* Copyright: @ded & @fat - Dustin Diaz, Jacob Thornton 2011
* Follow our software http://twitter.com/dedfat
* License: MIT
*/
!function(a,b,c){function w(a,c){var e=b.createElement("script"),f=0;e.onload=e[r]=function(){e[p]&&!!h.test(e[p])||f||(e.onload=e[r]=null,f=1,c())},e.async=1,e.src=a,d.parentNode.insertBefore(e,d)}function t(a,b){s(a,function(a){return!b(a)})}var d=b.getElementsByTagName("script")[0],e={},f={},g={},h=/^i|c/,i={},k="string",l=!1,m,n="push",o="DOMContentLoaded",p="readyState",q="addEventListener",r="onreadystatechange",s=function(a,b){for(m=0,j=a.length;m<j;++m)if(!b(a[m]))return 0;return 1};!b[p]&&b[q]&&(b[q](o,function u(){b.removeEventListener(o,u,l),b[p]="complete"},l),b[p]="loading");var v=function(a,b,d){function o(){if(!--l){e[k]=1,j&&j();for(var a in g)s(a.split("|"),m)&&!t(g[a],m)&&(g[a]=[])}}function m(a){return a.call?a():e[a]}a=a[n]?a:[a];var h=b&&b.call,j=h?b:d,k=h?a.join(""):b,l=a.length;c(function(){t(a,function(a){i[a]?(k&&(f[k]=1),o()):(i[a]=1,k&&(f[k]=1),w(v.path?v.path+a+".js":a,o))})},0);return v};v.get=w,v.ready=function(a,b,c){a=a[n]?a:[a];var d=[];!t(a,function(a){e[a]||d[n](a)})&&s(a,function(a){return e[a]})?b():!function(a){g[a]=g[a]||[],g[a][n](b),c&&c(d)}(a.join("|"));return v};var x=a.$script;v.noConflict=function(){a.$script=x;return this},typeof module!="undefined"&&module.exports?module.exports=v:a.$script=v}(this,document,setTimeout)
$script([
'jquery.min.js',
'syntaxhighlighter/shCore.js'], function(){
$script([
'syntaxhighlighter/shBrushJScript.js',
'syntaxhighlighter/shBrushXml.js',
'../angular.min.js'], function(){
$script([
'docs.js',
'doc_widgets.js',
'docs-keywords.js'], function(){
angular.compile(document)();
});
});
});
</script>
</head>
<body style="display:none;" ng:show="true">
<div id="header">
@ -28,6 +41,13 @@
<span class="main-title">{{partialTitle}}</span>
<a href="#" tabindex="0"><span class="angular">&lt;angular/&gt;</span> Docs</a>
</h1>
<ul class="navigation">
<li ng:class="selectedSection('intro')"><a href="#!intro">Introduction</a></li>
<li ng:class="selectedSection('tutorial')"><a href="#!tutoria">Tutorial</a></li>
<li ng:class="selectedSection('guide')"><a href="#!guide">Developer Guide</a></li>
<li ng:class="selectedSection('api')"><a href="#!api">API Reference</a></li>
<li ng:class="selectedSection('cookbook')"><a href="#!cookbook">Cookbook</a></li>
</ul>
</div>
<div id="sidebar">
<input type="text" name="search" id="search-box" placeholder="search the docs"

View file

@ -10,12 +10,20 @@ function output(docs, content, callback){
callback();
}
function parent(file) {
var parts = file.split('/');
parts.pop();
return parts.join('/');
}
exports.output = function(file, content, callback){
//console.log('writing', OUTPUT_DIR + file, '...');
fs.writeFile(
OUTPUT_DIR + file,
exports.toString(content),
callback);
console.log('write', file);
exports.makeDir(parent(OUTPUT_DIR + file), callback.waitFor(function(){
fs.writeFile(
OUTPUT_DIR + file,
exports.toString(content),
callback);
}));
};
@ -39,7 +47,8 @@ exports.toString = function toString(obj){
exports.makeDir = function (path, callback) {
var parts = path.split(/\//);
path = '.';
(function next(){
(function next(error){
if (error && error.code != 'EEXIST') return callback.error(error);
if (parts.length) {
path += '/' + parts.shift();
fs.mkdir(path, 0777, next);