BUG: Template option ignored

[CrossEye]

The option to use a custom template is ignored.

docco --template MyTemplate.jst --css MyCss.css MyFile.js

ignores the template option and simply uses the default layout.

It's easy enough to see the cause:

      if options.template
        unless options.css
          console.warn "docco: no stylesheet file specified"
        config.layout = null
      else
        dir = config.layout = path.join __dirname, 'resources', config.layout
        config.public       = path.join dir, 'public' if fs.existsSync path.join dir, 'public'
        config.template     = path.join dir, 'docco.jst'
        config.css          = options.css or path.join dir, 'docco.css'
      config.template = _.template fs.readFileSync(config.template).toString()

(which I found debugging the JS version.)

The problems is that

      if options.template
        unless options.css

should really be

      if config.template
        unless config.css

options is the whole Commander object. config is the combination of options.opts() and a default object.

I can write a PR to fix this, but I don't know the routine here. Do I change just the .litcoffee file and assume some CI build process fixes docco.js and index.html? Do I change that file and see if I can run the Cake file (which I've never done) to update these others before committing? Do I just manually change the three files and assume that I can match the expected Cake output properly?

Also, of course is the question of whether this is even being monitored. I see that the -- except for a minor URL change -- the last work here was three years ago. Is anyone listening?

---

The reason I was looking for a template was that I wanted to run docco against some individual files and be able to share the resulting HTML file standalone via email, chat file-share, etc.. This meant inlining the CSS into the default template (and possibly inlining the fonts inside that if I want offline availability.) This was easy enough to do on my own machine, just by cloning the parallel layout as inline and inlining there. But then I want to share the code with others on my team, and I would rather not fork just for this, but I could easily share a template. However, that only works if templates are working.

This also points to a slight problem with the requirement that to use --template, one must also supply --css. It's not a big deal for me. I can just point to an empty CSS file, but it's somewhat odd.

[jgonggrijp]

Definitely submit a pull request! Especially when the maintenance goes somewhat dormant, contributors can make a difference.

Edit the .litcoffee, then run cake before committing in order to keep the derived files in sync. @jashkenas likes it that way because it ensures the site and the transpiled source are always "ready to go".

Jeremy is extremely busy with his job at the New York Times and with his family life, but he still cares about the open source software he wrote. Some time might pass until he gets around to reviewing your pull request, but please take my word that he will appreciate it.

[CrossEye]

@jgonggrijp: Okay. PR #430 submitted.