From 11e9572b952e49b01035e956c412d6095533031a Mon Sep 17 00:00:00 2001
From: Misko Hevery
Date: Fri, 29 Apr 2011 15:18:27 -0700
Subject: Move documentation under individual headings

---
 docs/src/gen-docs.js          |  2 +-
 docs/src/ngdoc.js             | 43 +++++++++++++++++++++++++++++++++++++-----
 docs/src/reader.js            | 23 +++++++++++++---------
 docs/src/templates/docs.css   | 27 ++++++++++++++++++--------
 docs/src/templates/docs.js    | 20 ++++++++++++++------
 docs/src/templates/index.html | 44 +++++++++++++++++++++++++++++++------------
 docs/src/writer.js            | 21 +++++++++++++++------
 7 files changed, 133 insertions(+), 47 deletions(-)

(limited to 'docs/src')

diff --git a/docs/src/gen-docs.js b/docs/src/gen-docs.js
index 464916b1..9edfaceb 100644
--- a/docs/src/gen-docs.js
+++ b/docs/src/gen-docs.js
@@ -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());
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index 57202809..869fe4c5 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -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);
diff --git a/docs/src/reader.js b/docs/src/reader.js
index 300b17f0..f20bc06e 100644
--- a/docs/src/reader.js
+++ b/docs/src/reader.js
@@ -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();
diff --git a/docs/src/templates/docs.css b/docs/src/templates/docs.css
index f5b9275b..4f47367d 100644
--- a/docs/src/templates/docs.css
+++ b/docs/src/templates/docs.css
@@ -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;
 }
 
 
diff --git a/docs/src/templates/docs.js b/docs/src/templates/docs.js
index 9483496e..47bb87a6 100644
--- a/docs/src/templates/docs.js
+++ b/docs/src/templates/docs.js
@@ -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();
   };
diff --git a/docs/src/templates/index.html b/docs/src/templates/index.html
index 63e8d871..1c3dd3a6 100644
--- a/docs/src/templates/index.html
+++ b/docs/src/templates/index.html
@@ -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"
diff --git a/docs/src/writer.js b/docs/src/writer.js
index cf54e1a3..061b9f9f 100644
--- a/docs/src/writer.js
+++ b/docs/src/writer.js
@@ -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);
-- 
cgit v1.2.3