From 891309080ad896922c41ec75e07e171468a70c84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matias=20Niemel=C3=A4?= Date: Tue, 9 Jul 2013 18:08:23 -0400 Subject: [PATCH] chore(ngdoc): wrap all pages inside of a container tag for easy styling --- docs/content/tutorial/index.ngdoc | 214 ++++++++++++++-------------- docs/content/tutorial/the_end.ngdoc | 26 ++-- docs/spec/ngdocSpec.js | 64 +++++---- docs/src/ngdoc.js | 20 ++- docs/src/templates/css/docs.css | 11 +- 5 files changed, 184 insertions(+), 151 deletions(-) diff --git a/docs/content/tutorial/index.ngdoc b/docs/content/tutorial/index.ngdoc index 253906217ef5..3c0eebf821ea 100644 --- a/docs/content/tutorial/index.ngdoc +++ b/docs/content/tutorial/index.ngdoc @@ -1,117 +1,115 @@ @ngdoc overview -@name Tutorial +@name Tutorial: Index @description -
- A great way to get introduced to AngularJS is to work through this tutorial, which walks you through - the construction of an AngularJS web app. The app you will build is a catalog that displays a list - of Android devices, lets you filter the list to see only devices that interest you, and then view - details for any device. - - - - Work through the tutorial to see how Angular makes browsers smarter — without the use of extensions - or plug-ins. As you work through the tutorial, you will: - - * See examples of how to use client-side data binding and dependency injection to build dynamic - views of data that change immediately in response to user actions. - * See how Angular creates listeners on your data without the need for DOM manipulation. - * Learn a better, easier way to test your web apps. - * Learn how to use Angular services to make common web tasks, such as getting data into your app, - easier. - - And all of this works in any browser without modification to the browser! - - When you finish the tutorial you will be able to: - - * Create a dynamic application that works in any browser. - * Define the differences between Angular and common JavaScript frameworks. - * Understand how data binding works in AngularJS. - * Use the angular-seed project to quickly boot-strap your own projects. - * Create and run tests. - * Identify resources for learning more about AngularJS. - - The tutorial guides you through the entire process of building a simple application, including - writing and running unit and end-to-end tests. Experiments at the end of each step provide - suggestions for you to learn more about AngularJS and the application you are building. - - You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day - really digging into it. If you're looking for a shorter introduction to AngularJS, check out the - {@link misc/started Getting Started} document. - - - - - - - - # Working with the code - - You can follow this tutorial and hack on the code in either the Mac/Linux or the Windows - environment. The tutorial relies on the use of Git versioning system for source code management. - You don't need to know anything about Git to follow the tutorial. Select one of the tabs below - and follow the instructions for setting up your computer. - -
-
-
    -

  1. You will need Node.js and Karma to run unit tests, so please verify that you have +A great way to get introduced to AngularJS is to work through this tutorial, which walks you through +the construction of an AngularJS web app. The app you will build is a catalog that displays a list +of Android devices, lets you filter the list to see only devices that interest you, and then view +details for any device. + + + +Work through the tutorial to see how Angular makes browsers smarter — without the use of extensions +or plug-ins. As you work through the tutorial, you will: + +* See examples of how to use client-side data binding and dependency injection to build dynamic +views of data that change immediately in response to user actions. +* See how Angular creates listeners on your data without the need for DOM manipulation. +* Learn a better, easier way to test your web apps. +* Learn how to use Angular services to make common web tasks, such as getting data into your app, +easier. + +And all of this works in any browser without modification to the browser! + +When you finish the tutorial you will be able to: + +* Create a dynamic application that works in any browser. +* Define the differences between Angular and common JavaScript frameworks. +* Understand how data binding works in AngularJS. +* Use the angular-seed project to quickly boot-strap your own projects. +* Create and run tests. +* Identify resources for learning more about AngularJS. + +The tutorial guides you through the entire process of building a simple application, including +writing and running unit and end-to-end tests. Experiments at the end of each step provide +suggestions for you to learn more about AngularJS and the application you are building. + +You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day +really digging into it. If you're looking for a shorter introduction to AngularJS, check out the +{@link misc/started Getting Started} document. + + + + + + + +# Working with the code + +You can follow this tutorial and hack on the code in either the Mac/Linux or the Windows +environment. The tutorial relies on the use of Git versioning system for source code management. +You don't need to know anything about Git to follow the tutorial. Select one of the tabs below +and follow the instructions for setting up your computer. + +

    +
    +
      +

    1. You will need Node.js and Karma to run unit tests, so please verify that you have + Node.js v0.8 or better installed + and that the node executable is on your PATH by running the following + command in a terminal window:

      + 
      node --version
      +

      Additionally install Karma if you + don't have it already:

      + 
      npm install -g karma
      +

    2. You'll also need Git, which you can get from + the Git site.

      3. +

    3. Clone the angular-phonecat repository located at Github by running the following command:

      + 
      git clone git://github.com/angular/angular-phonecat.git
      +

      This command creates the angular-phonecat directory in your current +directory.

      4. +

    4. Change your current directory to angular-phonecat:

      + 
      cd angular-phonecat
      +

      The tutorial instructions assume you are running all commands from the angular-phonecat +directory.

      5. +

    5. You will need an http server running on your system. Mac and Linux machines typically +have Apache pre-installed, but If you don't already have one installed, you can use node +to run scripts/web-server.js, a simple bundled http server.

      6. +
    +
    + +
    +
      +

    1. You will need Node.js and Karma to run unit tests, so please verify that you have Node.js v0.8 or better installed and that the node executable is on your PATH by running the following command in a terminal window:

      node --version

      Additionally install Karma if you - don't have it already:

      + don't have it already:

      npm install -g karma
      -

    2. You'll also need Git, which you can get from - the Git site.

      3. -

    3. Clone the angular-phonecat repository located at Github by running the following command:

      - 
      git clone git://github.com/angular/angular-phonecat.git
      -

      This command creates the angular-phonecat directory in your current - directory.

      4. -

    4. Change your current directory to angular-phonecat:

      - 
      cd angular-phonecat
      -

      The tutorial instructions assume you are running all commands from the angular-phonecat - directory.

      5. -

    5. You will need an http server running on your system. Mac and Linux machines typically - have Apache pre-installed, but If you don't already have one installed, you can use node - to run scripts/web-server.js, a simple bundled http server.

      6. -
    -
    - -
    -
      -

    1. You will need Node.js and Karma to run unit tests, so please verify that you have - Node.js v0.8 or better installed - and that the node executable is on your PATH by running the following - command in a terminal window:

      - 
      node --version
      -

      Additionally install Karma if you - don't have it already:

      - 
      npm install -g karma
      -
      2. -

    2. You'll also need Git, which you can get from - the Git site.

      3. -

    3. Clone the angular-phonecat repository located at Github by running the following command:

      - 
      git clone git://github.com/angular/angular-phonecat.git
      -

      This command creates the angular-phonecat directory in your current directory.

      4. -

    4. Change your current directory to angular-phonecat:

      - 
      cd angular-phonecat
      -

      The tutorial instructions assume you are running all commands from the angular-phonecat - directory.

      -

      You should run all git commands from Git bash.

      -

      Other commands like test.bat or e2e-test.bat should be - executed from the Windows command line.

      5. -

    5. You need an http server running on your system, but if you don't already have one - already installed, you can use node to run scripts\web-server.js, a simple - bundled http server.

      6. -
    -
    - - The last thing to do is to make sure your computer has a web browser and a good text editor - installed. Now, let's get some cool stuff done! - - {@link step_00 Get Started!} -
    +
    2. +

  2. You'll also need Git, which you can get from + the Git site.

    3. +

  3. Clone the angular-phonecat repository located at Github by running the following command:

    + 
    git clone git://github.com/angular/angular-phonecat.git
    +

    This command creates the angular-phonecat directory in your current directory.

    4. +

  4. Change your current directory to angular-phonecat:

    + 
    cd angular-phonecat
    +

    The tutorial instructions assume you are running all commands from the angular-phonecat +directory.

    +

    You should run all git commands from Git bash.

    +

    Other commands like test.bat or e2e-test.bat should be +executed from the Windows command line.

    5. +

  5. You need an http server running on your system, but if you don't already have one +already installed, you can use node to run scripts\web-server.js, a simple +bundled http server.

    6. +
+
+ +The last thing to do is to make sure your computer has a web browser and a good text editor +installed. Now, let's get some cool stuff done! + +{@link step_00 Get Started!} diff --git a/docs/content/tutorial/the_end.ngdoc b/docs/content/tutorial/the_end.ngdoc index 142fb2b860e7..a4fd72a3d598 100644 --- a/docs/content/tutorial/the_end.ngdoc +++ b/docs/content/tutorial/the_end.ngdoc @@ -2,22 +2,20 @@ @name Tutorial: The End @description -
- Our application is now complete. Feel free to experiment with the code further, and jump back to - previous steps using the `git checkout` command. +Our application is now complete. Feel free to experiment with the code further, and jump back to +previous steps using the `git checkout` command. - For more details and examples of the Angular concepts we touched on in this tutorial, see the - {@link guide/ Developer Guide}. +For more details and examples of the Angular concepts we touched on in this tutorial, see the +{@link guide/ Developer Guide}. - For several more examples of code, see the {@link cookbook/ Cookbook}. +For several more examples of code, see the {@link cookbook/ Cookbook}. - When you are ready to start developing a project using Angular, we recommend that you bootstrap - your development with the {@link https://github.com/angular/angular-seed angular-seed} project. +When you are ready to start developing a project using Angular, we recommend that you bootstrap +your development with the {@link https://github.com/angular/angular-seed angular-seed} project. - We hope this tutorial was useful to you and that you learned enough about Angular to make you want - to learn more. We especially hope you are inspired to go out and develop Angular web apps of your - own, and that you might be interested in {@link misc/contribute contributing} to Angular. +We hope this tutorial was useful to you and that you learned enough about Angular to make you want +to learn more. We especially hope you are inspired to go out and develop Angular web apps of your +own, and that you might be interested in {@link misc/contribute contributing} to Angular. - If you have questions or feedback or just want to say "hi", please post a message at {@link - https://groups.google.com/forum/#!forum/angular}. -
+If you have questions or feedback or just want to say "hi", please post a message at {@link +https://groups.google.com/forum/#!forum/angular}. diff --git a/docs/spec/ngdocSpec.js b/docs/spec/ngdocSpec.js index 7a038e892450..128e01066310 100644 --- a/docs/spec/ngdocSpec.js +++ b/docs/spec/ngdocSpec.js @@ -59,10 +59,10 @@ describe('ngdoc', function() { '@param {function(number, string=)} d fn with optional arguments'); doc.parse(); expect(doc.param).toEqual([ - {name:'a', description:'

short

', type:'*', optional:false, 'default':undefined}, - {name:'b', description:'

med

', type:'Type', optional:false, 'default':undefined}, - {name:'c', description:'

long\nline

', type:'Class', optional:true, 'default':'2'}, - {name:'d', description:'

fn with optional arguments

', + {name:'a', description:'

short

', type:'*', optional:false, 'default':undefined}, + {name:'b', description:'

med

', type:'Type', optional:false, 'default':undefined}, + {name:'c', description:'

long\nline

', type:'Class', optional:true, 'default':'2'}, + {name:'d', description:'

fn with optional arguments

', type: 'function(number, string=)', optional: false, 'default':undefined} ]); }); @@ -72,7 +72,7 @@ describe('ngdoc', function() { doc.parse(); expect(doc.returns).toEqual({ type: 'Type', - description: '

text bold.

' + description: '

text bold.

' }); }); @@ -138,11 +138,25 @@ describe('ngdoc', function() { it('should not replace anything in 
, but escape the html escape the content', function() {
       expect(new Doc().markdown('bah x\n
\nangular.k\n
\n asdf x')).
         toEqual(
-            '
bah x\n' +
+            '
bah x\n' +
             '
\n' +
             '<b>angular</b>.k\n' +
             '
\n' +
-            ' asdf x
');
+            ' asdf x
');
+    });
+
+    it('should wrap everything inside a container tag', function() {
+      var doc = new Doc('@name superman').parse();
+      var content = doc.markdown('hello');
+
+      expect(content).toMatch('
hello
');
+    });
+
+    it('should use the content before a colon as the name prefix for the className of the tag container', function() {
+      var doc = new Doc('@name super: man').parse();
+      var content = doc.markdown('hello');
+
+      expect(content).toMatch('
hello
');
     });
 
     it('should replace text between two 
 tags', function() {
@@ -162,11 +176,11 @@ describe('ngdoc', function() {
           '\ngit bla bla\n\n' +
         '')).toEqual(
 
-        '
before
\n' +
+        '
before
\n' +
           '
\n' +
           'git bla bla\n' +
           '\n' +
-        '
');
+        '
');
       });
 
     it('should unindent text before processing based on the second line', function() {
@@ -290,7 +304,7 @@ describe('ngdoc', function() {
           name : 'number',
           optional: false,
           'default' : undefined,
-          description : '
Number \nto format.
' }]);
+          description : '
Number \nto format.
' }]);
       });
 
       it('should parse with default and optional', function() {
@@ -301,7 +315,7 @@ describe('ngdoc', function() {
           name : 'fractionSize',
           optional: true,
           'default' : '2',
-          description : '
desc
' }]);
+          description : '
desc
' }]);
       });
     });
 
@@ -311,8 +325,8 @@ describe('ngdoc', function() {
         doc.ngdoc = 'service';
         doc.parse();
         expect(doc.requires).toEqual([
-          {name:'$service', text:'
for \nA
'},
-          {name:'$another', text:'
for B
'}]);
+          {name:'$service', text:'
for \nA
'},
+          {name:'$another', text:'
for B
'}]);
         expect(doc.html()).toContain('$service');
         expect(doc.html()).toContain('$another');
         expect(doc.html()).toContain('
for \nA
');
@@ -364,7 +378,7 @@ describe('ngdoc', function() {
         var doc = new Doc("@name a\n@property {string} name desc rip tion");
         doc.parse();
         expect(doc.properties[0].name).toEqual('name');
-        expect(doc.properties[0].description).toEqual('
desc rip tion
');
+        expect(doc.properties[0].description).toEqual('
desc rip tion
');
       });
 
       it('should parse @property with type and description both', function() {
@@ -372,7 +386,7 @@ describe('ngdoc', function() {
         doc.parse();
         expect(doc.properties[0].name).toEqual('name');
         expect(doc.properties[0].type).toEqual('bool');
-        expect(doc.properties[0].description).toEqual('
desc rip tion
');
+        expect(doc.properties[0].description).toEqual('
desc rip tion
');
       });
 
     });
@@ -395,26 +409,26 @@ describe('ngdoc', function() {
       it('should parse @returns with type and description', function() {
         var doc = new Doc("@name a\n@returns {string} descrip tion");
         doc.parse();
-        expect(doc.returns).toEqual({type: 'string', description: '
descrip tion
'});
+        expect(doc.returns).toEqual({type: 'string', description: '
descrip tion
'});
       });
 
       it('should parse @returns with complex type and description', function() {
         var doc = new Doc("@name a\n@returns {function(string, number=)} description");
         doc.parse();
-        expect(doc.returns).toEqual({type: 'function(string, number=)', description: '
description
'});
+        expect(doc.returns).toEqual({type: 'function(string, number=)', description: '
description
'});
       });
 
       it('should transform description of @returns with markdown', function() {
         var doc = new Doc("@name a\n@returns {string} descrip *tion*");
         doc.parse();
-        expect(doc.returns).toEqual({type: 'string', description: '
descrip tion
'});
+        expect(doc.returns).toEqual({type: 'string', description: '
descrip tion
'});
       });
 
       it('should support multiline content', function() {
         var doc = new Doc("@name a\n@returns {string} description\n new line\n another line");
         doc.parse();
         expect(doc.returns).
-          toEqual({type: 'string', description: '
description\nnew line\nanother line
'});
+          toEqual({type: 'string', description: '
description\nnew line\nanother line
'});
       });
     });
 
@@ -423,18 +437,18 @@ describe('ngdoc', function() {
         var doc = new Doc("@name a\n@description 
abc
");
         doc.parse();
         expect(doc.description).
-          toBe('
<b>abc</b>
');
+          toBe('
<b>abc</b>
');
       });
 
       it('should support multiple pre blocks', function() {
         var doc = new Doc("@name a\n@description foo \n
abc
\n#bah\nfoo \n
cba
");
         doc.parse();
         expect(doc.description).
-          toBe('
foo \n' +
+          toBe('
foo \n' +
                '
abc
\n\n' +
                '
bah
\n\n' +
                '
foo \n' +
-               '
cba
');
+               '
cba
');
 
       });
 
@@ -477,7 +491,7 @@ describe('ngdoc', function() {
       it('should not remove {{}}', function() {
         var doc = new Doc('@name a\n@example text {{ abc }}');
         doc.parse();
-        expect(doc.example).toEqual('
text {{ abc }}
');
+        expect(doc.example).toEqual('
text {{ abc }}
');
       });
     });
 
@@ -496,10 +510,12 @@ describe('ngdoc', function() {
         doc.parse();
         expect(doc.html()).toContain('
Method\'s this
\n' +
             '
' +
+            '
' +
             '
I am self.
' +
+            '
' +
             '
\n');
         expect(doc.html()).toContain('
Method\'s this
\n' +
-            '
I am self.
');
+            '
I am self.
');
       });
     });
 
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index dc75d5cbac62..f5f22ee84ef8 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -240,7 +240,25 @@ Doc.prototype = {
         });
     });
     text = parts.join('');
-    text = markdown.makeHtml(text);
+
+    function prepareClassName(text) {
+      return text.toLowerCase().replace(/[_\W]+/g, '-');
+    };
+
+    var pageClassName, suffix = '-page';
+    if(this.name) {
+      var split = this.name.match(/^\s*(.+?)\s*:\s*(.+)/);
+      if(split && split.length > 1) {
+        var before = prepareClassName(split[1]);
+        var after = prepareClassName(split[2]);
+        pageClassName = before + suffix + ' ' + before + '-' + after + suffix;
+      }
+    }
+    pageClassName = pageClassName || prepareClassName(this.name || 'docs') + suffix;
+
+    text = '
' + 
+             markdown.makeHtml(text) +
+           '
';
     text = text.replace(/(?:
)?(REPLACEME\d+)(?:<\/p>)?/g, function(_, id) {
       return placeholderMap[id];
     });
diff --git a/docs/src/templates/css/docs.css b/docs/src/templates/css/docs.css
index 01aa23765577..a34a197ff532 100644
--- a/docs/src/templates/css/docs.css
+++ b/docs/src/templates/css/docs.css
@@ -293,13 +293,16 @@ ul.events > li > h3 {
   z-index:1031;
 }
 
+.tutorial-index-page,
+.tutorial-the-end-page {
+  padding-top:50px;
+}
+
 .tutorial-page {
   position:relative;
 }
-.tutorial-page-no-nav {
-  padding-top:50px;
-}
-.tutorial-page-no-nav .improve-docs {
+
+.tutorial-page .improve-docs {
   position:absolute;
   top:0;
   right:0;