From 8d27393aa20afe9e0cba211e08957183587540e4 Mon Sep 17 00:00:00 2001 From: Micheil Smith Date: Thu, 18 Nov 2010 12:26:37 +1100 Subject: [PATCH] Generate Table of Contents at compile time. --- Makefile | 4 +- doc/api_assets/core.js | 70 ++++---------------------- tools/doctool/doctool.js | 127 ++++++++++++++++++++++++++++++++--------------- 3 files changed, 99 insertions(+), 102 deletions(-) diff --git a/Makefile b/Makefile index 4564d80..3c9039d 100644 --- a/Makefile +++ b/Makefile @@ -77,10 +77,10 @@ build/doc/api/assets/%: doc/api_assets/% build/doc/api/assets/ build/doc/%: doc/% cp $< $@ -build/doc/api/%.html: doc/api/%.markdown build/default/node $(apidoc_dirs) $(apiassets) +build/doc/api/%.html: doc/api/%.markdown build/default/node $(apidoc_dirs) $(apiassets) tools/doctool/doctool.js build/default/node tools/doctool/doctool.js doc/template.html $< > $@ -build/doc/changelog.html: ChangeLog build/default/node build/doc/ $(apidoc_dirs) $(apiassets) +build/doc/changelog.html: ChangeLog build/default/node build/doc/ $(apidoc_dirs) $(apiassets) tools/doctool/doctool.js build/default/node tools/doctool/doctool.js doc/template.html $< \ | sed 's|assets/|api/assets/|g' \ | sed 's|||g' > $@ diff --git a/doc/api_assets/core.js b/doc/api_assets/core.js index 3625b2d..c185a77 100644 --- a/doc/api_assets/core.js +++ b/doc/api_assets/core.js @@ -1,63 +1,13 @@ $(function(){ highlight(undefined, undefined, 'pre'); - var $headings = $("h2, h3, h4, h5, h6"); - - if(! $("body").hasClass("index") && $headings.size() > 2){ - var current_level - , last_level = 0 - , toc = [ - '
', - '

Table Of Contents Hide

' - ]; - - for(var i=0, hl=$headings.size()+1; i < hl; i++) { - var heading = $headings[i] || false; - if(heading) { - current_level = heading.tagName.substr(1,1); - - console.log(current_level, last_level, $(heading).text()); - - if(last_level != 0 && current_level <= last_level) { - toc.push(""); - } - - if(current_level > last_level) { - toc.push(""); - toc.push(""); - } - } - - if(current_level == last_level || current_level < last_level) { - toc.push("
  • "); - } - - toc.push(''+$(heading).text()+''); - last_level = current_level; - } else { - toc.push("
    • "); - toc.push(""); - } - } - - toc.push(""); - toc.push(""); - toc.push("
    "); - toc.push("
    "); - - $("#container header").after(toc.join("\n")); - $("#toggler").toggle(function(e){ - $("#toc ul").hide(); - $(this).text("show"); - e.preventDefault(); - }, function(e){ - $("#toc ul").show(); - $(this).text("hide"); - e.preventDefault(); - }); - } + + $('Hide').appendTo($("#toc h2")).toggle(function(e){ + $("#toc ul").hide(); + $(this).text("Show"); + e.preventDefault(); + }, function(e){ + $("#toc ul").show(); + $(this).text("Hide"); + e.preventDefault(); + }); }); diff --git a/tools/doctool/doctool.js b/tools/doctool/doctool.js index 4f3c6d4..4b4f2f0 100644 --- a/tools/doctool/doctool.js +++ b/tools/doctool/doctool.js @@ -1,9 +1,9 @@ /* Process a single doc file - argv[2] = template file - argv[3] = input file - argv[4] = output file + argv[2] = template file + argv[3] = input file + argv[4] = output file */ var fs = require("fs"), @@ -14,9 +14,8 @@ var fs = require("fs"), var template = fs.readFileSync(argv[2], "utf8"); -var ids = {}; -function formatIdString(str){ +function formatIdString(str) { str = str .replace(/\([^)}]*\)/gmi, "") .replace(/[^A-Za-z0-9_.]+/gmi, "_"); @@ -25,59 +24,107 @@ function formatIdString(str){ } -var includeExpr = /^@include\s+([A-Za-z0-9-_]+)(?:\.)?([a-zA-Z]*)$/gmi; -function convertData(data, current_file){ - // Allow including other pages in the data. - function loadIncludes(data){ - return data.replace(includeExpr, function(src, name, ext){ - try { - var include_path = path.join(current_file, "../", name+"."+(ext || "markdown")) - return loadIncludes(fs.readFileSync(include_path, "utf8")); - } catch(e) { - return ""; +function generateToc(data) { + var last_level = 0 + , first_level = 0 + , toc = [ + '
    ', + '

    Table Of Contents

    ' + ]; + + data.replace(/(^#+)\W+([^$\n]+)/gmi, function(src, level, text) { + level = level.length; + + if (first_level == 0) first_level = level; + + if (level <= last_level) { + toc.push(""); + } + + if (level > last_level) { + toc.push(""); + toc.push(""); } - }); - }; + } - data = loadIncludes(data); + toc.push("
  • "); + toc.push(''+text+''); - // Convert it to HTML from Markdown - if(data.length == 0){ - data = "Sorry, this section is currently undocumented, but we'll be working on it."; + last_level = level; + }); + + for(var c=last_level-first_level; 0 <= c ; c-- ) { + toc.push("
    • "); + toc.push(""); } - data = markdown.toHTML(markdown.parse(data), {xhtml:true}); + toc.push("
    ") + toc.push("
    "); + + return toc.join(""); +} - data = data.replace(/
    <\/hr>/g, "
    "); - data = data.replace(/(\([^<]+)(\<\/h[1-6]\>)/gmi, function(o, ts, c, te){ - var id = formatIdString(c); - return ts+' id="'+id+'">'+c+te; +var includeExpr = /^@include\s+([A-Za-z0-9-_]+)(?:\.)?([a-zA-Z]*)$/gmi; +// Allow including other pages in the data. +function loadIncludes(data, current_file) { + return data.replace(includeExpr, function(src, name, ext) { + try { + var include_path = path.join(current_file, "../", name+"."+(ext || "markdown")) + return loadIncludes(fs.readFileSync(include_path, "utf8"), current_file); + } catch(e) { + return ""; + } }); +} - return data; -}; -if(argc > 3){ - var filename = argv[3]; +function convertData(data) { + // Convert it to HTML from Markdown + var html = markdown.toHTML(markdown.parse(data), {xhtml:true}) + .replace(/
    <\/hr>/g, "
    ") + .replace(/(\([^<]+)(\<\/h[1-6]\>)/gmi, function(o, ts, c, te) { + return ts+' id="'+formatIdString(c)+'">'+c+te; + }); + + return html; +} + - fs.readFile(filename, "utf8", function(err, data){ - if(err) throw err; +if (argc > 3) { + var filename = argv[3], + output = template, + html; - // do conversion stuff. - var html = convertData(data, filename); - var output = template.replace("{{content}}", html); + fs.readFile(filename, "utf8", function(err, data) { + if (err) throw err; + // go recursion. + data = loadIncludes(data, filename); + // go markdown. + html = convertData(data); filename = path.basename(filename, '.markdown'); - if(filename == "index"){ - output = output.replace("{{section}}", ""); - output = output.replace(/]*)>/, ''); - } else { + if (filename != "_toc" && filename != "index") { + if (data) { + html = generateToc(data) + "\n" + html; + } + output = output.replace("{{section}}", filename+" - ") + } else { + output = output.replace("{{section}}", ""); + output = output.replace(/]*)>/, ''); + } + if (html.length == 0) { + html = "Sorry, this section is currently undocumented, \ +but we'll be working on it."; } + output = output.replace("{{content}}", html); - if(argc > 4) { + if (argc > 4) { fs.writeFile(argv[4], output); } else { process.stdout.write(output); -- 2.7.4