Merge pull request #1300 from hargasinski/scrollspy

added scroll-spy behaviour (fixes #1289)
caolan · Oct 11, 2016 · 7d6ec8b · 7d6ec8b
2 parents 0d2dbf7 + 5c0ac6e
commit 7d6ec8b
Show file tree

Hide file tree

Showing 4 changed files with 113 additions and 22 deletions.
diff --git a/support/jsdoc/jsdoc-custom.js b/support/jsdoc/jsdoc-custom.js
@@ -96,10 +96,22 @@ $(function initSearchBar() {
             location.href = host + suggestion;
         // handle searching from one of the source files or the home page
         } else if (currentPage !== 'docs.html') {
-            location.href = host + 'docs.html#.' + suggestion;
+            location.href = host + 'docs.html#' + suggestion;
         } else {
-            var $el = document.getElementById('.' + suggestion);
-            $('#main').animate({ scrollTop: $el.offsetTop - 60 }, 500);
+            var $el = document.getElementById(suggestion);
+            $('#main-container').animate({ scrollTop: $el.offsetTop - 60 }, 500);
         }
     });
+
+    function fixOldHash() {
+        var hash = window.location.hash;
+        if (hash) {
+            var hashMatches = hash.match(/^#\.(\w+)$/);
+            if (hashMatches) {
+                window.location.hash = '#'+hashMatches[1];
+            }
+        }
+    }
+
+    fixOldHash();
 });
diff --git a/support/jsdoc/jsdoc-fix-html.js b/support/jsdoc/jsdoc-fix-html.js
@@ -11,6 +11,7 @@ var pageTitle = 'Methods:';
 var docFilename = 'docs.html';
 var mainModuleFile = 'module-async.html';
 var mainSectionId = '#main';
+var mainScrollableSection = '#main-container';
 var sectionTitleClass = '.page-title';
 
 var HTMLFileBegin = '<!DOCTYPE html>\n<html lang="en">\n<head>\n';
@@ -21,6 +22,12 @@ var additionalFooterText = ' Documentation has been modified from the original.
     ' For more information, please see the <a href="https://github.com/caolan/async">async</a> repository.';
 
 function generateHTMLFile(filename, $page, callback) {
+    var methodName = filename.match(/\/(\w+)\.js\.html$/);
+    if (methodName) {
+        var $thisMethodDocLink = $page.find('#toc').find('a[href="'+docFilename+'#'+methodName[1]+'"]');
+        $thisMethodDocLink.parent().addClass('active');
+    }
+
     // generate an HTML file from a cheerio object
     var HTMLdata = HTMLFileBegin + $page.find('head').html()
         + HTMLFileHeadBodyJoin + $page.find('body').html()
@@ -74,7 +81,7 @@ function combineFakeModules(files, callback) {
                 var $modulePage = $(moduleData);
                 var moduleName = $modulePage.find(sectionTitleClass).text();
                 $modulePage.find(sectionTitleClass).attr('id', moduleName.toLowerCase());
-                $mainPage.find(mainSectionId).append($modulePage.find(mainSectionId).html());
+                $mainPage.find(mainScrollableSection).append($modulePage.find(mainScrollableSection).html());
                 return fileCallback();
             });
         }, function(err) {
@@ -109,14 +116,44 @@ function applyPreCheerioFixes(data) {
 }
 
 
-function fixToc($page, moduleFiles) {
+function scrollSpyFix($page, $nav) {
+    // move everything into one big ul (for Bootstrap scroll-spy)
+    var $ul = $nav.children('ul');
+    $ul.addClass('nav').addClass('methods');
+    $ul.find('.methods').each(function() {
+        var $methodsList = $(this);
+        var $methods = $methodsList.find('[data-type="method"]');
+        var $parentLi = $methodsList.parent();
+
+        $methodsList.remove();
+        $methods.remove();
+        $parentLi.after($methods);
+        $parentLi.addClass('toc-header');
+
+    });
+
+    $page.find('[data-type="method"]').addClass("toc-method");
+
+    $page.find('[id^="."]').each(function() {
+        var $ele = $(this);
+        var id = $(this).attr('id');
+        $ele.attr('id', id.replace('.', ''));
+    });
+}
+
+function fixToc(file, $page, moduleFiles) {
     // remove `async` listing from toc
-    $page.find('li').find('a[href="'+mainModuleFile+'"]').parent().remove();
+    $page.find('a[href="'+mainModuleFile+'"]').parent().remove();
 
     // change toc title
-    $page.find('nav').children('h3').text(pageTitle);
-    $page.find('nav').children('h2').remove();
+    var $nav = $page.find('nav');
+    $nav.attr('id', 'toc');
+    $nav.children('h3').text(pageTitle);
+    $nav.children('h2').remove();
+
+    scrollSpyFix($page, $nav);
 
+    var prependFilename = (file === docFilename) ? '' : docFilename;
     // make everything point to the same 'docs.html' page
     _.each(moduleFiles, function(filename) {
         $page.find('[href^="'+filename+'"]').each(function() {
@@ -126,10 +163,10 @@ function fixToc($page, moduleFiles) {
             // category titles should sections title, while everything else
             // points to the correct listing
             if (href === filename) {
-                var moduleName = $ele.text().toLowerCase().replace(/\s/g, '');
-                $ele.attr('href', docFilename+'#'+moduleName);
+                var moduleName = $ele.text().toLowerCase().replace(/\s/g, '').replace('.', '');
+                $ele.attr('href', prependFilename+'#'+moduleName);
             } else {
-                $ele.attr('href', href.replace(filename, docFilename));
+                $ele.attr('href', href.replace(filename, prependFilename).replace('#.', '#'));
             }
         });
     });
@@ -139,7 +176,7 @@ function fixFooter($page) {
     // add a note to the footer that the documentation has been modified
     var $footer = $page.find('footer');
     $footer.append(additionalFooterText);
-    $page.find('#main').append($footer);
+    $page.find(mainScrollableSection).append($footer);
 }
 
 function fixModuleLinks(files, callback) {
@@ -152,7 +189,7 @@ function fixModuleLinks(files, callback) {
             if (err) return fileCallback(err);
             var $file = $(applyPreCheerioFixes(fileData));
 
-            fixToc($file, moduleFiles);
+            fixToc(file, $file, moduleFiles);
             fixFooter($file);
             $file.find('[href="'+mainModuleFile+'"]').attr('href', docFilename);
             generateHTMLFile(filePath, $file, fileCallback);

diff --git a/support/jsdoc/theme/static/styles/jsdoc-default.css b/support/jsdoc/theme/static/styles/jsdoc-default.css
@@ -112,18 +112,25 @@ tt, code, kbd, samp {
   bottom: 0;
   float: none;
   min-width: 360px;
-  overflow-y: auto;
-  padding-left: 16px;
-  padding-right: 16px;
+  overflow-y: hidden;
+}
+
+#main-container {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    overflow-y: scroll;
+    padding-left: 16px;
+    padding-right: 16px;
 }
 
-#main h1 {
+#main-container h1 {
     margin-top: 100px !important;
     padding-top: 0px;
     border-left: 2px solid #3391FE;
 }
 
-#main h4 {
+#main-container h4 {
     margin-top: 120px !important;
     padding-top: 0px;
     padding-left: 16px;
@@ -141,6 +148,39 @@ section, h1 {
   padding: 2em 30px 0;
 }
 
+#toc > h3 {
+    margin-bottom: 0px;
+}
+
+#toc > .methods > li {
+    padding: 0px 10px;
+}
+
+#toc > .methods > li > a {
+    font-size: 12px;
+    padding: 0px;
+}
+
+#toc > .methods > .toc-header {
+    margin-top: 10px;
+}
+
+#toc > .methods > .toc-method {
+    padding: 0px;
+    margin: 0px 10px;
+}
+
+#toc > .methods > .toc-method > a,
+#toc > .methods > .toc-method > a.active {
+    padding: 0px 0px 0px 20px;
+    border-left: 1px solid #D8DCDF;
+    color: #98999A;
+}
+
+#toc > .methods > .toc-method.active {
+    background-color: #E8E8E8;
+}
+
 .nav.navbar-right .navbar-form {
     padding: 0;
     margin: 6px 0px;

diff --git a/support/jsdoc/theme/tmpl/layout.tmpl b/support/jsdoc/theme/tmpl/layout.tmpl
@@ -66,11 +66,13 @@
 <label for="nav-trigger" class="overlay"></label>
 
 <div id="main">
-    <?js if (title != 'Home') { ?>
-    <h1 class="page-title"><?js= title ?></h1>
-    <?js } ?>
+    <div id="main-container" data-spy="scroll" data-target="#toc" data-offset="50">
+        <?js if (title != 'Home') { ?>
+        <h1 class="page-title"><?js= title ?></h1>
+        <?js } ?>
 
-    <?js= content ?>
+        <?js= content ?>
+    </div>
 </div>
 
 <nav>