chore(docs): generate header ids for better linking

- generate ids for all headers
- collect defined anchors
- check broken links (even if the page exists, but the anchor/id does not)

2 files changed, 90 insertions, 27 deletions

diff --git a/docs/spec/domSpec.js b/docs/spec/domSpec.js
index 7bc6a7f4..d10db9dc 100644
--- a/docs/spec/domSpec.js
+++ b/docs/spec/domSpec.js
@@ -1,4 +1,5 @@
 var DOM = require('../src/dom.js').DOM;
+var normalizeHeaderToId = require('../src/dom.js').normalizeHeaderToId;
 
 describe('dom', function() {
   var dom;
@@ -7,6 +8,31 @@ describe('dom', function() {
     dom = new DOM();
   });
 
+  describe('html', function() {
+    it('should add ids to all h tags', function() {
+      dom.html('<h1>Some Header</h1>');
+      expect(dom.toString()).toContain('<h1 id="some-header">Some Header</h1>');
+    });
+
+    it('should collect <a name> anchors too', function() {
+      dom.html('<h2>Xxx <a name="foo"></a> and bar <a name="bar"></a>');
+      expect(dom.anchors).toContain('foo');
+      expect(dom.anchors).toContain('bar');
+    })
+  });
+
+  it('should collect h tag ids', function() {
+    dom.h('Page Title', function() {
+      dom.html('<h1>Second</h1>xxx <h2>Third</h2>');
+      dom.h('Another Header', function() {});
+    });
+
+    expect(dom.anchors).toContain('page-title');
+    expect(dom.anchors).toContain('second');
+    expect(dom.anchors).toContain('second_third');
+    expect(dom.anchors).toContain('another-header');
+  });
+
   describe('h', function() {
 
     it('should render using function', function() {
@@ -25,7 +51,7 @@ describe('dom', function() {
         this.html('<h1>sub-heading</h1>');
       });
       expect(dom.toString()).toContain('<h1 id="heading">heading</h1>');
-      expect(dom.toString()).toContain('<h2>sub-heading</h2>');
+      expect(dom.toString()).toContain('<h2 id="sub-heading">sub-heading</h2>');
     });
 
     it('should properly number nested headings', function() {
@@ -40,12 +66,45 @@ describe('dom', function() {
 
       expect(dom.toString()).toContain('<h1 id="heading">heading</h1>');
       expect(dom.toString()).toContain('<h2 id="heading2">heading2</h2>');
-      expect(dom.toString()).toContain('<h3>heading3</h3>');
+      expect(dom.toString()).toContain('<h3 id="heading2_heading3">heading3</h3>');
 
       expect(dom.toString()).toContain('<h1 id="other1">other1</h1>');
-      expect(dom.toString()).toContain('<h2>other2</h2>');
+      expect(dom.toString()).toContain('<h2 id="other2">other2</h2>');
+    });
+
+
+    it('should add nested ids to all h tags', function() {
+      dom.h('Page Title', function() {
+        dom.h('Second', function() {
+          dom.html('some <h1>Third</h1>');
+        });
+      });
+
+      var resultingHtml = dom.toString();
+      expect(resultingHtml).toContain('<h1 id="page-title">Page Title</h1>');
+      expect(resultingHtml).toContain('<h2 id="second">Second</h2>');
+      expect(resultingHtml).toContain('<h3 id="second_third">Third</h3>');
+    });
+
+  });
+
+
+  describe('normalizeHeaderToId', function() {
+    it('should ignore content in the parenthesis', function() {
+      expect(normalizeHeaderToId('One (more)')).toBe('one');
+    });
+
+    it('should ignore html content', function() {
+      expect(normalizeHeaderToId('Section <a name="section"></a>')).toBe('section');
     });
 
+    it('should ignore special characters', function() {
+      expect(normalizeHeaderToId('Section \'!?')).toBe('section');
+    });
+
+    it('should ignore html entities', function() {
+      expect(normalizeHeaderToId('angular&#39;s-jqlite')).toBe('angulars-jqlite');
+    });
   });
 
 });
diff --git a/docs/spec/ngdocSpec.js b/docs/spec/ngdocSpec.js
index 607745d8..15fd0ba4 100644
--- a/docs/spec/ngdocSpec.js
+++ b/docs/spec/ngdocSpec.js
@@ -262,33 +262,37 @@ describe('ngdoc', function() {
       expect(docs[0].events).toEqual([eventA, eventB]);
       expect(docs[0].properties).toEqual([propA, propB]);
     });
+  });
 
 
+  describe('checkBrokenLinks', function() {
+    var docs;
 
-    describe('links checking', function() {
-      var docs;
-      beforeEach(function() {
-        spyOn(console, 'log');
-        docs = [new Doc({section: 'api', id: 'fake.id1', links: ['non-existing-link']}),
-                new Doc({section: 'api', id: 'fake.id2'}),
-                new Doc({section: 'api', id: 'fake.id3'})];
-      });
-
-      it('should log warning when any link doesn\'t exist', function() {
-        ngdoc.merge(docs);
-        expect(console.log).toHaveBeenCalled();
-        expect(console.log.argsForCall[0][0]).toContain('WARNING:');
-      });
+    beforeEach(function() {
+      spyOn(console, 'log');
+      docs = [new Doc({section: 'api', id: 'fake.id1', anchors: ['one']}),
+              new Doc({section: 'api', id: 'fake.id2'}),
+              new Doc({section: 'api', id: 'fake.id3'})];
+    });
 
-      it('should say which link doesn\'t exist', function() {
-        ngdoc.merge(docs);
-        expect(console.log.argsForCall[0][0]).toContain('non-existing-link');
-      });
+    it('should log warning when a linked page does not exist', function() {
+      docs.push(new Doc({section: 'api', id: 'with-broken.link', links: ['non-existing-link']}))
+      ngdoc.checkBrokenLinks(docs);
+      expect(console.log).toHaveBeenCalled();
+      var warningMsg = console.log.argsForCall[0][0]
+      expect(warningMsg).toContain('WARNING:');
+      expect(warningMsg).toContain('non-existing-link');
+      expect(warningMsg).toContain('api/with-broken.link');
+    });
 
-      it('should say where is the non-existing link', function() {
-        ngdoc.merge(docs);
-        expect(console.log.argsForCall[0][0]).toContain('api/fake.id1');
-      });
+    it('should log warning when a linked anchor does not exist', function() {
+      docs.push(new Doc({section: 'api', id: 'with-broken.link', links: ['api/fake.id1#non-existing']}))
+      ngdoc.checkBrokenLinks(docs);
+      expect(console.log).toHaveBeenCalled();
+      var warningMsg = console.log.argsForCall[0][0]
+      expect(warningMsg).toContain('WARNING:');
+      expect(warningMsg).toContain('non-existing');
+      expect(warningMsg).toContain('api/with-broken.link');
     });
   });
 
@@ -524,7 +528,7 @@ describe('ngdoc', function() {
         doc.ngdoc = 'filter';
         doc.parse();
         expect(doc.html()).toContain(
-            '<h3 id="Animations">Animations</h3>\n' +
+            '<h3 id="usage_animations">Animations</h3>\n' +
             '<div class="animations">' +
               '<ul>' +
                 '<li>enter - Add text</li>' +
@@ -541,7 +545,7 @@ describe('ngdoc', function() {
         var doc = new Doc('@ngdoc overview\n@name angular\n@description\n#heading\ntext');
         doc.parse();
         expect(doc.html()).toContain('text');
-        expect(doc.html()).toContain('<h2>heading</h2>');
+        expect(doc.html()).toContain('<h2 id="heading">heading</h2>');
         expect(doc.html()).not.toContain('Description');
       });
     });