Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Comparing changes

Choose two branches to see what's changed or to start a new pull request. If you need to, you can also compare across forks.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks.
  • 9 commits
  • 5 files changed
  • 0 commit comments
  • 2 contributors
Commits on Mar 24, 2012
@grncdr grncdr Add a very simple --json switch
When using JSON output, only an index.json is written.
f460e39
Commits on Mar 25, 2012
@grncdr grncdr Use optimist for option parsing, add --stdout flag
Command-line options changed so that you can optionally specify a --renderer
or --parser instead of the --github-wiki/--json and --requirejs/--commonjs flags.

The --stdout flag causes each rendered documentation file to be printed to
standard out rather than written to a file. It is probably not useful except
with --renderer json.
7ac9608
@omarkhan Fix package.json 3021f7b
@omarkhan Show help if called with no arguments 82915e3
@omarkhan CommonJSParser exported twice c053099
@omarkhan Do not try to make resources dir when using --stdout 2c04813
@omarkhan Move preprocessing logic to separate renderer method 623a14f
@omarkhan Update readme 78df95b
@omarkhan 0.1.15 323cf67
View
8 README.md
@@ -69,10 +69,10 @@ CoffeeDoc can be run from the command line:
Usage: coffeedoc [options] [targets]
Options:
- -o, --output : Set output directory (default: ./docs)
- --commonjs : Use if target scripts use CommonJS for module loading (default)
- --requirejs : Use if target scripts use RequireJS for module loading
- --github-wiki: Use if generating Markdown for Github wiki
+ --output, -o Set output directory [default: "docs"]
+ --parser Parser to use. Available parsers: commonjs,requirejs [default: "commonjs"]
+ --renderer Renderer to use. Available renderers: html,gfm,json [default: "html"]
+ --stdout Direct all output to stdout instead of files [boolean]
If [targets] is a directory, CoffeeDoc will recursively document all `.coffee`
files found under that directory.
View
5 package.json
@@ -8,7 +8,7 @@
"coffeescript"
],
"author": "Omar Khan",
- "version": "0.1.14",
+ "version": "0.1.15",
"licenses": [
{
"type": "MIT",
@@ -20,7 +20,8 @@
},
"dependencies": {
"coffee-script": ">=1.1.1",
- "eco": ">=1.1.0-rc-1"
+ "eco": ">=1.1.0-rc-1",
+ "optimist": ">=0.3.1"
},
"bin": {
"coffeedoc": "./bin/coffeedoc"
View
123 src/docgen.coffee
@@ -12,53 +12,40 @@ coffeedoc = require(__dirname + '/coffeedoc')
parsers = require(__dirname + '/parsers')
renderers = require(__dirname + '/renderers')
-
# Command line options
-OPTIONS =
- '-o, --output ': 'Set output directory (default: ./docs)'
- '--commonjs ': 'Use if target scripts use CommonJS for module loading (default)'
- '--requirejs ': 'Use if target scripts use RequireJS for module loading'
- '--github-wiki': 'Use if generating Markdown for Github wiki'
-
-help = ->
- ### Show help message and exit ###
- console.log('Usage: coffeedoc [options] [targets]\n')
- console.log('Options:')
- for flag, description of OPTIONS
- console.log(' ' + flag + ': ' + description)
+opts = require('optimist')
+ .usage('''Usage: coffeedoc [options] [targets]''')
+ .describe('output', 'Set output directory')
+ .default('output', 'docs')
+ .alias('o', 'output')
+ .describe('parser', "Parser to use. Available parsers: #{Object.keys(parsers)}")
+ .default('parser', 'commonjs')
+ .describe('renderer', "Renderer to use. Available renderers: #{Object.keys(renderers)}")
+ .default('renderer', 'html')
+ .describe('stdout', 'Direct all output to stdout instead of files')
+ .boolean('stdout')
+ .describe('help', 'Show this help.')
+ .alias('h', 'help')
+
+argv = opts.argv
+
+if argv.help or argv._.length == 0
+ opts.showHelp()
process.exit()
-opts = process.argv[2...process.argv.length]
-if opts.length == 0 then help()
-
-outputdir = 'docs'
-for o, idx in opts
- if o == '-o' or o == '--output'
- outputdir = opts[idx + 1]
- opts.splice(idx, 2)
- break
-
-if '-h' in opts or '--help' in opts
- help()
-
-if '--commonjs' in opts
- opts.shift()
- parser = new parsers.CommonJSParser()
-else if '--requirejs' in opts
- opts.shift()
- parser = new parsers.RequireJSParser()
-else
- parser = new parsers.CommonJSParser()
-
-if '--github-wiki' in opts
- rendercls = renderers.GithubWikiRenderer
- opts.shift()
-else
- rendercls = renderers.HtmlRenderer
+rendercls = renderers[argv.renderer]
+if not rendercls?
+ console.error "Invalid renderer: #{argv.renderer}\n"
+ opts.showHelp()
+ process.exit()
-if opts.length == 0
- opts = ['.']
+parsercls = parsers[argv.parser]
+if not parsercls?
+ console.error "Invalid parser: #{argv.parser}\n"
+ opts.showHelp()
+ process.exit()
+parser = new parsercls()
# Get source file paths
sources = []
@@ -67,25 +54,26 @@ getSourceFiles = (target) ->
sources.push(target)
else if fs.statSync(target).isDirectory()
getSourceFiles(path.join(target, p)) for p in fs.readdirSync(target)
-getSourceFiles(o) for o in opts
+getSourceFiles(o) for o in argv._
sources.sort()
-renderer = new rendercls(outputdir, sources)
+renderer = new rendercls(argv.output, sources)
if sources.length > 0
modules = []
- # Make output directory
- if path.existsSync(outputdir)
- # Recursively delete outputdir if it already exists
- rm = (target) ->
- if fs.statSync(target).isDirectory()
- rm(path.join(target, p)) for p in fs.readdirSync(target)
- fs.rmdirSync(target)
- else
- fs.unlinkSync(target)
- rm(outputdir)
- fs.mkdirSync(outputdir, '755')
+ # Unless we are printing to stdout, make output directory
+ if not argv.stdout
+ if path.existsSync(argv.output)
+ # Recursively delete argv.output if it already exists
+ rm = (target) ->
+ if fs.statSync(target).isDirectory()
+ rm(path.join(target, p)) for p in fs.readdirSync(target)
+ fs.rmdirSync(target)
+ else
+ fs.unlinkSync(target)
+ rm(argv.output)
+ fs.mkdirSync(argv.output, '755')
# Iterate over source scripts
source_names = (s.replace(/\.coffee$/, '') for s in sources)
@@ -95,13 +83,14 @@ if sources.length > 0
resourcepath = 'resources/'
if source.indexOf('/') != -1 and renderer.shouldMakeSubdirs()
- docpath = outputdir
+ docpath = argv.output
sourcepath = source.split('/')
for dir in sourcepath[0...sourcepath.length - 1]
resourcepath = '../' + resourcepath
- docpath = path.join(docpath, dir)
- if not path.existsSync(docpath)
- fs.mkdirSync(docpath, '755')
+ if not argv.stdout
+ docpath = path.join(docpath, dir)
+ if not path.existsSync(docpath)
+ fs.mkdirSync(docpath, '755')
# Fetch documentation information
@@ -123,11 +112,14 @@ if sources.length > 0
cls.parent_module = module_path
cls.parent_name = clspath.join('.')
- # Generate docs
- result = renderer.renderModule(documentation)
+ # Apply preprocessing to the documentation as defined by the selected renderer
+ renderer.preprocess(documentation)
- # Write to file
- fs.writeFile(path.join(outputdir, documentation.filename + renderer.fileExtension()), result)
+ # If there is no filename do not output this modules documentation
+ if documentation.filename and not argv.stdout
+ # Generate docs for current module
+ result = renderer.renderModule(documentation)
+ fs.writeFile(path.join(argv.output, documentation.filename + renderer.fileExtension()), result)
# Save to modules array for the index page
modules.push(documentation)
@@ -135,5 +127,8 @@ if sources.length > 0
# Make index page
index = renderer.renderIndex(modules)
- fs.writeFile(path.join(outputdir, renderer.indexFile()), index)
+ if argv.stdout
+ process.stdout.write(index)
+ else
+ fs.writeFile(path.join(argv.output, renderer.indexFile()), index)
renderer.finish()
View
7 src/parsers.coffee
@@ -41,7 +41,7 @@ class BaseParser
return []
-exports.CommonJSParser = class CommonJSParser extends BaseParser
+class CommonJSParser extends BaseParser
###
Parses code written according to CommonJS specifications:
@@ -86,7 +86,7 @@ exports.CommonJSParser = class CommonJSParser extends BaseParser
when n.type == 'Assign' and n.value.type == 'Code')
-exports.RequireJSParser = class RequireJSParser extends BaseParser
+class RequireJSParser extends BaseParser
###
Not yet tested
###
@@ -241,3 +241,6 @@ exports.RequireJSParser = class RequireJSParser extends BaseParser
getFunctions: (nodes) ->
return (n for n in nodes \
when n.type == 'Assign' and n.value.type == 'Code')
+
+exports.commonjs = CommonJSParser
+exports.requirejs = RequireJSParser
View
35 src/renderers.coffee
@@ -8,6 +8,13 @@ class Renderer
this.outputdir = outputdir
this.sources = sources
+ preprocess: (context) ->
+ ###
+ This method should apply any transformations to module documentation
+ before it is passed to the template. Transformations should be made in
+ place - the return value is ignored.
+ ###
+
renderIndex: (modules) =>
eco.render(this.index_template, modules: modules)
@@ -37,15 +44,16 @@ class HtmlRenderer extends Renderer
obj.docstring = showdown.makeHtml(obj.docstring)
return null
- renderModule: (context) =>
- # Convert markdown to html
+ preprocess: (context) =>
+ ###
+ Convert markdown to html.
+ ###
this._renderMarkdown(context.module)
for c in context.module.classes
this._renderMarkdown(c)
this._renderMarkdown(m) for m in c.staticmethods
this._renderMarkdown(m) for m in c.instancemethods
this._renderMarkdown(f) for f in context.module.functions
- super(context)
moduleFilename: (x) ->
return x + '.coffee'
@@ -96,16 +104,29 @@ class GithubWikiRenderer extends Renderer
moduleFilename: (x) =>
return this._wikiize(x)
- renderModule: (context) =>
+ preprocess: (context) =>
context.wikiize = this._wikiize
context.quoteMarkdown = this._quoteMarkdown
context.params = this._params
- super(context)
fileExtension: -> '.md'
indexFile: -> 'ModuleIndex.md'
shouldMakeSubdirs: -> false
+class JSONRenderer extends Renderer
+ constructor: (outputdir, sources) ->
+ this.outputdir = outputdir
+ this.sources = sources
+
+ renderIndex: JSON.stringify
+
+ renderModule: JSON.stringify
+
+ shouldMakeSubdirs: -> false
+ moduleFilename: (x) -> false # No individual file output
+ fileExtension: -> '.doc.json'
+ indexFile: -> 'index.doc.json'
-exports.GithubWikiRenderer = GithubWikiRenderer
-exports.HtmlRenderer = HtmlRenderer
+exports.html = HtmlRenderer
+exports.gfm = GithubWikiRenderer
+exports.json = JSONRenderer

No commit comments for this range

Something went wrong with that request. Please try again.