[WIP] The big update (finally)

[jbt]

So this is the big update I've been alluding to in #75 and various other places for months now. Sorry everyone for letting stuff rot so badly. Truth is I just haven't had the time to address this properly. But now I've finally straightened everything I've been tinkering on recently and this is where things're at.

Really should've committed this as I went along but it was all too messy and none of it worked until very recently.

This is pretty much a chuck-everything-out-the-window-and-rewrite-it job. Various bits have been kept around but a lot has been redone from scratch.

Notable Changes

• Swap showdown out for markdown-it (which is nicer to use and better-maintained than marked)
• Wherever possible, kill off in-house code in favour of modules, no point repeating other people's work especially when it's done much better
• Kill off pygments and use highlight.js. This changes the languages available for highlighting, but makes everything waaaaay faster, easier to work with, and doesn't require the messy pygments child process stuff. It also changes the available colour schemes, which isn't great, sorry :(
• Some messy stuff that I still want to clean up for grabbing colour schemes straight from the highlight.js styles and feeding them into LESS
• Oh yeah, switch from sass to less for styles because native node = yay

This has been done in pretty much exactly the wrong style: lots of code, a lot of which isn't self-explanatory, and not many comments. Before I get this into master I'll make sure it's up-to-scratch with comments.

This update includes a few breaking changes and as such I'm tempted to make this a 1.0 release when it's ready. And once I'm done with the TODOs below it may include a few more/

Issues this addresses

• Closes #32 Use Marked (superseded, decided to go for markdown-it instead)
• Closes #33 LESS support (also closes #91, duplicate of the same)
• Closes #53 Investigate atom/highlights (superseded, highlight.js turned out better for support and performance)
• Closes #74 Installation issues (specific to pygments, which has been stripped out altogether)
• Closes #75 (obviously)
• Closes #77 Table support in markdown
• Closes #82
• Closes #85 "err" class in js syntax not supported by pygments (highlight.js does way better)
• Disproves(ish) and closes #99
• Supersedes and closes #93 (typofix)

  Remaining TODOs

These are things I'd really like to incorporate into this PR before publishing it as a big update to npm

• [x] Investigate switching back to dox for multiline comment parsing - it's been updated a lot since switching away, and it should help with #70
• [x] Go back over everything and comment-erize it much better
• [x] Address #54 properly, possibly using https://github.com/cowboy/node-toc
• [x] Address #59 - all relative links can just have .html added to them. This should be much nicer with markdown-it thanks to its pluggability
• [ ] Look into #41 if possible (dropping watcher for node core fs.watch) the lack of recursive support on non-osx/non-windows makes this too hard for the scope of this
• [x] Add a proper license: #81
• [x] For the bits I have copy/pasted around in docker.js, make sure they're in as near as possible the same order as before to avoid unnecessary diff churn - looks like I've moved stuff around a bit more than necessary
• [ ] Look into publishing under a new name. This ideally would be done in parallel with stuff under the existing name for people who want to keep using it. Current thinking would be to rename to [something else] and make the docker package on npm a thin wrapper which includes the necessary requires and bin scripts.

[chrisfls]

I'm very happy that you didn't let docker "die", it's pretty much my favourite doc generation tool for node.

[daedalus28]

Any update on this? Also, any chance of renaming the project with the advent of docker (containers)? The command line tool is tricky now for docker users :P

[jbt]

Yeahh sorry, other work stuff has been keeping me busy. Poor show from me :(

I'll try and get this rounded off as much as possible and hopefully push a beta-tagged release to npm over the weekend.

And yeah the container docker has become sufficiently popular now that renaming is looking important. I'll probably do that as part of this too so it doesn't get too confusing with things moving around. But obviously I need to figure out how to do that without breaking what's already there. I have some ideas on that front.

[alinex]

Sounds very good, I also hope to get a release soon.

[gaurav21r]

@jbt Grrrrrrrrreat work! Any updates?

[jbt]

Sorry, I'm being terrible here. January was a super-busy month and I haven't been able to give this the time it deserves. I'll try and spend a bit more time on this in the next couple of days

[jbt]

Righty then. I just published v1.0.0-alpha.1 under the next tag so if anyone's interested you can now npm install docker@next and see what I've broken.

Most noticeable breaking change is complete ditching of Pygments and therefore all its colour schemes, so you now need to use a colour scheme from highlight.js, which you can find over here.

Let me know of any quirks you find or anything else that needs tweaking prior to actually releasing this properly.

Meanwhile I'll get figuring out a tactic for renaming this to a something else and how to make that work nicely.

[gaurav21r]

@jbt On behalf of the entire community, THAANKSSS :+1:

How about extending an existing project since this has a greater feature set? jsdoc-plus or docco-plus? I'm sure npm module names are available. Could also get docgen available by talking to its author.

Any specific thing you are looking for while naming?

[tarunc]

Just a note, looks like you might be missing a debounce dependency in docker@next. Just tried running it, got this:

> docker

module.js:341
    throw err;
    ^

Error: Cannot find module 'debounce'
    at Function.Module._resolveFilename (module.js:339:15)
    at Function.Module._load (module.js:290:25)
    at Module.require (module.js:367:17)
    at require (internal/module.js:16:19)
    at Object.<anonymous> (/<root>/node_modules/docker/src/docker.js:47:16)
    at Module._compile (module.js:413:34)
    at Object.Module._extensions..js (module.js:422:10)
    at Module.load (module.js:357:32)
    at Function.Module._load (module.js:314:12)
    at Module.require (module.js:367:17)

It works if you install debounce manually tho. Nice work overall!

[jbt]

Oh good spot, not sure how I managed that! I'll get a 1.0.0-alpha.2 out with that fixed up shortly

[alinex]

Great work, I could get the new version working and got a great documentation. Read more under http://alinex.github.io/2016/03/01/docker.html

I will have a deeper look the next weeks. And hope to include mermaid or plantuml.

[jbt]

Right, once and for all I am getting this rounded off.

v1.0.0-alpha.4 is on npm as docker@next for anyone who wants to check I haven't done a silly.

I'll remove the alpha and publish as docker@latest this afternoon unless there's anything horribly broken with it.

In the meantime I'll get down to writing the entry in History.md for this update, which will be quite large.