Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

added scroll-spy behaviour (fixes #1289) #1300

Merged
merged 6 commits into from
Oct 11, 2016
Merged

added scroll-spy behaviour (fixes #1289) #1300

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
06b1c9c
docs: combine toc sublists into one list
hargasinski Oct 7, 2016
0b7ebe4
docs: added Bootstrap scroll-spy
hargasinski Oct 8, 2016
f71da34
docs: highlight current method in toc when viewing source file
hargasinski Oct 8, 2016
98dced3
docs: update old id links to new ones
hargasinski Oct 8, 2016
59e9cda
docs: using jQuery/cheerio builtins for adding class
hargasinski Oct 9, 2016
5c0ac6e
docs: update searching to use new ids
hargasinski Oct 11, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
12 changes: 12 additions & 0 deletions support/jsdoc/jsdoc-custom.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,4 +102,16 @@ $(function initSearchBar() {
$('#main').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();
});
57 changes: 47 additions & 10 deletions support/jsdoc/jsdoc-fix-html.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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()
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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() {
Expand All @@ -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('#.', '#'));
}
});
});
Expand All @@ -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) {
Expand All @@ -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);
Expand Down
50 changes: 45 additions & 5 deletions support/jsdoc/theme/static/styles/jsdoc-default.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
10 changes: 6 additions & 4 deletions support/jsdoc/theme/tmpl/layout.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down