Skip to content
Browse files

Updates based on feedback:

 - Remove 'vendor' directory reference from install task.
 - Filter out unknown sources in document(), instead of generate_documentation(), to ensure template usage of sources only includes those that will be documented (e.g. 'Jump Page').

 Cleanup:
  - Remove usage of lib/docco in Cakefile, this can prevent building if the last compiled version has errors.
  - Remove 'weigh' task from Cakefile (it's cool but kind of unneeded)
  • Loading branch information...
1 parent 7af1961 commit 85d1ffe4669689f2bae9f138c9794aebb0b3baf1 @justindujardin justindujardin committed
Showing with 32 additions and 61 deletions.
  1. +3 −1 .gitignore
  2. +2 −31 Cakefile
  3. +6 −9 index.html
  4. +15 −10 lib/docco.js
  5. +6 −10 src/docco.coffee
View
4 .gitignore
@@ -1,3 +1,5 @@
.DS_Store
output
-docs
+docs
+test/data
+node_modules
View
33 Cakefile
@@ -1,4 +1,4 @@
-Docco = require './lib/docco'
+Docco = require './src/docco'
CoffeeScript = require 'coffee-script'
{spawn, exec} = require 'child_process'
fs = require 'fs'
@@ -16,7 +16,7 @@ task 'install', 'install the `docco` command into /usr/local (or --prefix)', (op
lib = base + '/lib/docco'
exec([
'mkdir -p ' + lib
- 'cp -rf bin README resources vendor lib ' + lib
+ 'cp -rf bin README resources lib ' + lib
'ln -sf ' + lib + '/bin/docco ' + base + '/bin/docco'
].join(' && '), (err, stdout, stderr) ->
if err then console.error stderr
@@ -31,35 +31,6 @@ task 'doc', 'rebuild the Docco documentation', ->
throw err if err
)
-task 'weigh', 'display docco.coffee line count distribution', ->
- # Parse out code/doc sections for `docco.cofeee`
- file_path = path.join __dirname, 'src/docco.coffee'
- file_contents = fs.readFileSync(file_path, 'utf-8').toString()
- file_lines = file_contents.split '\n'
- sections = Docco.parse file_path, file_contents, true
-
- # Iterate over the sections and determine lines of code,
- # documentation, and whitespace.
- docs_count = code_count = 0
- for section in sections
- code_count += 1 for l in section.code_text.split('\n') when l.trim() != ''
- docs_count += 1 for l in section.docs_text.split('\n') when l.trim() != ''
- blank_count = file_lines.length - docs_count - code_count
- total_count = docs_count+code_count+blank_count
- if total_count != file_lines.length
- throw "Total line count mismatch between file and computed values"
-
- # Print summary information.
- console.log [
- "docco.coffee line counts:"
- "------------------------"
- " Documentation : #{docs_count}"
- " Code : #{code_count}"
- " Whitespace : #{blank_count}"
- "------------------------"
- " Total : #{total_count}"
- ].join('\n')
-
task 'test', 'run the Docco test suite', ->
runTests Docco
View
15 index.html
@@ -52,9 +52,6 @@ <h3 id="partnersincrime">Partners in Crime:</h3>
and merging them into an HTML template.</p> </td> <td class="code"> <div class="highlight"><pre><span class="nv">generate_documentation = </span><span class="nf">(source, config, callback) -&gt;</span>
<span class="nx">fs</span><span class="p">.</span><span class="nx">readFile</span> <span class="nx">source</span><span class="p">,</span> <span class="s2">&quot;utf-8&quot;</span><span class="p">,</span> <span class="nf">(error, code) -&gt;</span>
<span class="k">throw</span> <span class="nx">error</span> <span class="k">if</span> <span class="nx">error</span>
- <span class="k">if</span> <span class="o">not</span> <span class="nx">get_language</span> <span class="nx">source</span>
- <span class="nx">console</span><span class="p">.</span><span class="nx">error</span> <span class="s2">&quot;error: skipping unknown file type -&gt; #{source}&quot;</span>
- <span class="k">return</span> <span class="nx">callback</span><span class="p">()</span>
<span class="nv">sections = </span><span class="nx">parse</span> <span class="nx">source</span><span class="p">,</span> <span class="nx">code</span><span class="p">,</span> <span class="nx">config</span><span class="p">.</span><span class="nx">blocks</span>
<span class="nx">highlight</span> <span class="nx">source</span><span class="p">,</span> <span class="nx">sections</span><span class="p">,</span> <span class="o">-&gt;</span>
<span class="nx">generate_html</span> <span class="nx">source</span><span class="p">,</span> <span class="nx">sections</span><span class="p">,</span> <span class="nx">config</span>
@@ -231,19 +228,19 @@ <h3 id="partnersincrime">Partners in Crime:</h3>
<ol>
<li>Construct config to use by taking <code>defaults</code> first, then merging in <code>options</code></li>
-<li>Generate the source list to iterate over and document. </li>
+<li>Generate the resolved source list, filtering out unknown types.</li>
<li>Load the specified template and css files.</li>
<li>Ensure the output path is created, write out the CSS style file,
-document and output HTML for each source, and finally invoke the
-completion callback, if it is specified.</li>
+document each source, and invoke the completion callback, if it is specified.</li>
</ol> </td> <td class="code"> <div class="highlight"><pre><span class="nb">document</span> <span class="o">=</span> <span class="nf">(sources,options={},callback=null) -&gt;</span>
<span class="nv">config = </span><span class="p">{}</span>
<span class="nx">config</span><span class="p">[</span><span class="nx">key</span><span class="p">]</span> <span class="o">=</span> <span class="nx">defaults</span><span class="p">[</span><span class="nx">key</span><span class="p">]</span> <span class="k">for</span> <span class="nx">key</span><span class="p">,</span><span class="nx">value</span> <span class="k">of</span> <span class="nx">defaults</span>
<span class="nx">config</span><span class="p">[</span><span class="nx">key</span><span class="p">]</span> <span class="o">=</span> <span class="nx">value</span> <span class="k">for</span> <span class="nx">key</span><span class="p">,</span><span class="nx">value</span> <span class="k">of</span> <span class="nx">options</span> <span class="k">if</span> <span class="nx">key</span> <span class="k">of</span> <span class="nx">defaults</span>
- <span class="nv">files = </span><span class="p">[]</span>
- <span class="nv">files = </span><span class="nx">files</span><span class="p">.</span><span class="nx">concat</span><span class="p">(</span><span class="nx">exports</span><span class="p">.</span><span class="nx">resolve_source</span><span class="p">(</span><span class="nx">src</span><span class="p">))</span> <span class="k">for</span> <span class="nx">src</span> <span class="k">in</span> <span class="nx">sources</span>
- <span class="nv">config.sources = </span><span class="nx">files</span>
+ <span class="nv">resolved = </span><span class="p">[]</span>
+ <span class="nv">resolved = </span><span class="nx">resolved</span><span class="p">.</span><span class="nx">concat</span><span class="p">(</span><span class="nx">resolve_source</span><span class="p">(</span><span class="nx">src</span><span class="p">))</span> <span class="k">for</span> <span class="nx">src</span> <span class="k">in</span> <span class="nx">sources</span>
+ <span class="nv">config.sources = </span><span class="nx">resolved</span><span class="p">.</span><span class="nx">filter</span><span class="p">(</span><span class="nf">(source) -&gt;</span> <span class="nx">get_language</span> <span class="nx">source</span><span class="p">).</span><span class="nx">sort</span><span class="p">()</span>
+ <span class="nx">console</span><span class="p">.</span><span class="nx">log</span> <span class="s2">&quot;docco: skipped unknown type (#{m})&quot;</span> <span class="k">for</span> <span class="nx">m</span> <span class="k">in</span> <span class="nx">resolved</span> <span class="k">when</span> <span class="nx">m</span> <span class="o">not</span> <span class="k">in</span> <span class="nx">config</span><span class="p">.</span><span class="nx">sources</span>
<span class="nv">config.docco_template = </span><span class="nx">template</span> <span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="nx">config</span><span class="p">.</span><span class="nx">template</span><span class="p">).</span><span class="nx">toString</span><span class="p">()</span>
<span class="nv">docco_styles = </span><span class="nx">fs</span><span class="p">.</span><span class="nx">readFileSync</span><span class="p">(</span><span class="nx">config</span><span class="p">.</span><span class="nx">css</span><span class="p">).</span><span class="nx">toString</span><span class="p">()</span>
View
25 lib/docco.js
@@ -1,14 +1,11 @@
(function() {
- var commander, defaults, document, ensure_directory, exec, ext, fs, generate_documentation, generate_html, get_language, highlight, highlight_end, highlight_start, key, l, languages, parse, path, resolve_source, run, showdown, spawn, template, value, version, _ref, _ref2;
+ var commander, defaults, document, ensure_directory, exec, ext, fs, generate_documentation, generate_html, get_language, highlight, highlight_end, highlight_start, key, l, languages, parse, path, resolve_source, run, showdown, spawn, template, value, version, _ref, _ref2,
+ __indexOf = Array.prototype.indexOf || function(item) { for (var i = 0, l = this.length; i < l; i++) { if (i in this && this[i] === item) return i; } return -1; };
generate_documentation = function(source, config, callback) {
return fs.readFile(source, "utf-8", function(error, code) {
var sections;
if (error) throw error;
- if (!get_language(source)) {
- console.error("error: skipping unknown file type -> " + source);
- return callback();
- }
sections = parse(source, code, config.blocks);
return highlight(source, sections, function() {
generate_html(source, sections, config);
@@ -221,7 +218,7 @@
};
document = function(sources, options, callback) {
- var config, docco_styles, files, key, src, value, _i, _len;
+ var config, docco_styles, key, m, resolved, src, value, _i, _j, _len, _len2;
if (options == null) options = {};
if (callback == null) callback = null;
config = {};
@@ -235,16 +232,24 @@
config[key] = value;
}
}
- files = [];
+ resolved = [];
for (_i = 0, _len = sources.length; _i < _len; _i++) {
src = sources[_i];
- files = files.concat(exports.resolve_source(src));
+ resolved = resolved.concat(resolve_source(src));
+ }
+ config.sources = resolved.filter(function(source) {
+ return get_language(source);
+ }).sort();
+ for (_j = 0, _len2 = resolved.length; _j < _len2; _j++) {
+ m = resolved[_j];
+ if (__indexOf.call(config.sources, m) < 0) {
+ console.log("docco: skipped unknown type (" + m + ")");
+ }
}
- config.sources = files;
config.docco_template = template(fs.readFileSync(config.template).toString());
docco_styles = fs.readFileSync(config.css).toString();
return ensure_directory(config.output, function() {
- var next_file;
+ var files, next_file;
fs.writeFileSync(path.join(config.output, path.basename(config.css)), docco_styles);
files = config.sources.slice();
next_file = function() {
View
16 src/docco.coffee
@@ -58,9 +58,6 @@
generate_documentation = (source, config, callback) ->
fs.readFile source, "utf-8", (error, code) ->
throw error if error
- if not get_language source
- console.error "error: skipping unknown file type -> #{source}"
- return callback()
sections = parse source, code, config.blocks
highlight source, sections, ->
generate_html source, sections, config
@@ -322,19 +319,19 @@ run = (args=process.argv) ->
# Run Docco over a list of `sources` with the given `options`.
#
# 1. Construct config to use by taking `defaults` first, then merging in `options`
-# 2. Generate the source list to iterate over and document.
+# 2. Generate the resolved source list, filtering out unknown types.
# 3. Load the specified template and css files.
# 4. Ensure the output path is created, write out the CSS style file,
-# document and output HTML for each source, and finally invoke the
-# completion callback, if it is specified.
+# document each source, and invoke the completion callback, if it is specified.
document = (sources,options={},callback=null) ->
config = {}
config[key] = defaults[key] for key,value of defaults
config[key] = value for key,value of options if key of defaults
- files = []
- files = files.concat(exports.resolve_source(src)) for src in sources
- config.sources = files
+ resolved = []
+ resolved = resolved.concat(resolve_source(src)) for src in sources
+ config.sources = resolved.filter((source) -> get_language source).sort()
+ console.log "docco: skipped unknown type (#{m})" for m in resolved when m not in config.sources
config.docco_template = template fs.readFileSync(config.template).toString()
docco_styles = fs.readFileSync(config.css).toString()
@@ -368,7 +365,6 @@ resolve_source = (source) ->
# ### Exports
# Information about docco, and functions for programatic usage.
-
exports[key] = value for key, value of {
run : run
document : document

0 comments on commit 85d1ffe

Please sign in to comment.
Something went wrong with that request. Please try again.