watch option to auto generate files based on file changes

[Dinis Cruz]

Is there a way to run the main docco command in a watch mode? (for example node_modules/.bin/groc src/*.coffee)

Basically the same thing as mocha does with the -w option

[Keith Cirkel]

Hey @DinisCruz thanks for the issue! You could use a tool like watch or nodemon to do just this. If you have any troubles with these just shout and we'll be able to help.

Implementing something like this in Docco doesn't really fit the philosophy of the tool - especially when other tools are easily available to wrap it, so I'm going to close this one.

[Jeremy Ashkenas]

Let's tag 'em as we close 'em.

But in general — Docco is a documentation tool. You don't usually want to be re-reading all of your docs every time you make an edit to a source file ... so there's not much reason for us to include a watch mode directly.

[Dinis Cruz]

I think a 'watch' solution is very useful since it really helps when making changes to see its impact as soon as possible (REPL style). But I can see how this might be done using another tool or as part of a CI set-up (maybe an wiki page with ideas could be added to docco?)

[Dinis Cruz]

For reference here is a modification of the existing Cakefile which creates the documentation every time a file in the srcFolder is modified:

{spawn, exec} = require 'child_process'
fs            = require 'fs'
path          = require 'path'
srcFolder     = './src'

option '-w', '--watch'          , 'continually build the docco files (in /docs'
option '-l', '--layout [LAYOUT]', 'specify the layout for Docco\'s docs'
option '-v', '--verbose'        , 'show docco console out'

task 'doc', 'rebuild the Docco documentation', (options) ->
  layout = options.layout or 'linear'
  run_Task = ()->
    console.time('docco build in')
    commands =  [ "node_modules/.bin/docco --layout #{layout} #{srcFolder}/**/**.**"
                  "node_modules/.bin/docco --layout #{layout} #{srcFolder}/**.**"]
    execResult = (err,stdout, stderr) ->
      throw err if err
      console.log stdout if options.verbose

    (exec commands.join(' && '), execResult).on 'exit', -> console.timeEnd('docco build in')

  if (options.watch)
    console.log "Watching folder: #{srcFolder}"
    fs.watch srcFolder, ()->
        console.log "Folder watch on #{srcFolder} triggered"
        run_Task()

  run_Task()

this can be executed with cake -w -l classic doc

here is what my UI looks like (when running this code)

actually, the way I like to run these is via ``npm run` so this is what it looks like when I add the cake command to package.json

[Dinis Cruz]

The updated version you can see at o2platform/fluentnode#21 (comment) also auto commits to the gh-pages branch of the respective GitHub repo

So now, as soon as I save a change to a source file:

1. docco runs
2. the changes are committed locally
3. the commit is pushed into the gh-pages branch
4. the docs website is updated (this last step is done by github)

... which is a pretty cool workflow