refactor(docs): improved the visual rendering of the documentation pages

Author: mhevery

docs/src/dom.js

@@ -74,6 +74,10 @@ DOM.prototype = {
     });
   },
 
+  div: function(attr, text) {
+    this.tag('div', attr, text);
+  },
+
   h: function(heading, content, fn){
     if (content==undefined || (content instanceof Array && content.length == 0)) return;
     this.headingDepth++;

docs/src/ngdoc.js

@@ -222,11 +222,12 @@ Doc.prototype = {
           if (!match) {
             throw new Error("Not a valid 'property' format: " + text);
           }
-          var property = {
+          var property = new Doc({
               type: match[1],
               name: match[2],
+              shortName: match[2],
               description: self.markdown(text.replace(match[0], match[4]))
-            };
+            });
           self.properties.push(property);
         } else if(atName == 'eventType') {
           match = text.match(/^([^\s]*)\s+on\s+([\S\s]*)/);
@@ -482,44 +483,60 @@ Doc.prototype = {
 
   method_properties_events: function(dom) {
     var self = this;
-    dom.h('Methods', this.methods, function(method){
-      var signature = (method.param || []).map(property('name'));
-      dom.h(method.shortName + '(' + signature.join(', ') + ')', method, function() {
-        dom.html(method.description);
-        method.html_usage_parameters(dom);
-        self.html_usage_this(dom);
-        method.html_usage_returns(dom);
-
-        dom.h('Example', method.example, dom.html);
-      });
-    });
-    dom.h('Properties', this.properties, function(property){
-      dom.h(property.shortName, function() {
-       dom.html(property.description);
-       dom.h('Example', property.example, dom.html);
-      });
-    });
-    dom.h('Events', this.events, function(event){
-    dom.h(event.shortName, event, function() {
-        dom.html(event.description);
-        if (event.type == 'listen') {
-          dom.tag('div', {class:'inline'}, function() {
-            dom.h('Listen on:', event.target);
-          });
-        } else {
-          dom.tag('div', {class:'inline'}, function() {
-            dom.h('Type:', event.type);
+    if (self.methods.length) {
+      dom.div({class:'member method'}, function(){
+        dom.h('Methods', self.methods, function(method){
+          var signature = (method.param || []).map(property('name'));
+          dom.h(method.shortName + '(' + signature.join(', ') + ')', method, function() {
+            dom.html(method.description);
+            method.html_usage_parameters(dom);
+            self.html_usage_this(dom);
+            method.html_usage_returns(dom);
+
+            dom.h('Example', method.example, dom.html);
           });
-          dom.tag('div', {class:'inline'}, function() {
-            dom.h('Target:', event.target);
+        });
+      });
+    }
+    if (self.properties.length) {
+      dom.div({class:'member property'}, function(){
+        dom.h('Properties', self.properties, function(property){
+          dom.h(property.shortName, function() {
+           dom.html(property.description);
+           if (!property.html_usage_returns) {
+             console.log(property);
+           }
+           property.html_usage_returns(dom);
+           dom.h('Example', property.example, dom.html);
           });
-        }
-        event.html_usage_parameters(dom);
-        self.html_usage_this(dom);
+        });
+      });
+    }
+    if (self.events.length) {
+      dom.div({class:'member event'}, function(){
+        dom.h('Events', self.events, function(event){
+          dom.h(event.shortName, event, function() {
+            dom.html(event.description);
+            if (event.type == 'listen') {
+              dom.tag('div', {class:'inline'}, function() {
+                dom.h('Listen on:', event.target);
+              });
+            } else {
+              dom.tag('div', {class:'inline'}, function() {
+                dom.h('Type:', event.type);
+              });
+              dom.tag('div', {class:'inline'}, function() {
+                dom.h('Target:', event.target);
+              });
+            }
+            event.html_usage_parameters(dom);
+            self.html_usage_this(dom);
 
-        dom.h('Example', event.example, dom.html);
+            dom.h('Example', event.example, dom.html);
+          });
+        });
       });
-    });
+    }
   },
 
   parameters: function(dom, separator, skipFirst, prefix) {

docs/src/templates/docs.css

@@ -53,6 +53,42 @@ li {
   border: 1px solid red;
 }
 
+.member {
+  border: 1px solid gray;
+  margin: 2em 0;
+}
+
+.member p {
+  padding: 0;
+}
+
+.member>h2 {
+  background-color: lightgray;
+  padding: .2em .4em;
+  margin: 0;
+  border-bottom: 1px solid gray;
+}
+
+.member>ul {
+  list-style: none;
+  padding: 0;
+}
+
+.member>ul>li {
+  border: 1px solid lightgray;
+  margin: 1em;
+
+}
+.member>ul>li>h3 {
+  background-color: #EEE;
+  padding: .2em .4em;
+  margin: 0;
+  font-family: monospace;
+  border-bottom: 1px solid lightgray;
+}
+.member>ul>li>div {
+  padding: 1em;
+}
 
 /*----- Upgrade IE Prompt -----*/
 

docs/src/templates/docs.js

@@ -152,6 +152,14 @@ function TutorialInstructionsCtrl($cookieStore) {
 window.angular = window.angular || {};
 angular.module = angular.module || {};
 
-angular.module.ngdocs = function($locationProvider) {
+angular.module.ngdocs = function($locationProvider, $filterProvider) {
   $locationProvider.html5Mode(true).hashPrefix('!');
+
+  $filterProvider.register('title', function(){
+    return function(text) {
+      return text && text.replace(/^angular\.module\.([^\.]+)(\.(.*))?$/, function(_, module, _0, name){
+        return 'Module ' + module + (name ? ' - ' + name : '');
+      });
+    }
+  });
 };

docs/src/templates/index.html

@@ -6,7 +6,7 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   <meta name="fragment" content="!">
-  <title ng:bind-template="AngularJS: {{partialTitle}}">AngularJS</title>
+  <title ng:bind-template="AngularJS: {{partialTitle | title}}">AngularJS</title>
   <script type="text/javascript">
     // dynamically add base tag as well as css and javascript files.
     // we can't add css/js the usual way, because some browsers (FF) eagerly prefetch resources
@@ -115,7 +115,7 @@
 
 
     <div class="content-panel">
-      <h2 ng:bind="partialTitle"></h2>
+      <h2 ng:bind="partialTitle | title"></h2>
       <ng:include id="content"
                   class="content-panel-content"
                   src="getCurrentPartial()"