Snippit maintenance / automatic doc generation

[dthree]

For intro comments, see 419654c

[dthree]

@sindresorhus you originally brought up this point. After over a month of work on it, I think I've got this problem pretty well wrapped up.

I'd love to get your present feedback / advice on it. If you have a second, could you try this out:

$ npm install -g wat
$ wat tour

This will walk you through what wat can do now.

@wooorm @Qix- @anko feedback from you guys as well would be awesome!

[anko]

It looked neat, then I got to generating the chalk docs, which exited with 1 and errored:

fs.js:549
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                                                  ^

Error: EACCES: permission denied, open '/usr/lib/node_modules/wat/dist/clerk/../../config/index.json'
    at Error (native)
    at Object.fs.openSync (fs.js:549:18)
    at Object.fs.writeFileSync (fs.js:1161:15)
    at Object.write (/usr/lib/node_modules/wat/dist/clerk/indexer.js:377:8)
    at /usr/lib/node_modules/wat/dist/autodocs/autodocs.js:78:38
    at checker (/usr/lib/node_modules/wat/dist/clerk/indexer.js:103:9)
    at /usr/lib/node_modules/wat/dist/clerk/indexer.js:112:7
    at Walker.<anonymous> (/usr/lib/node_modules/wat/dist/clerk/indexer.js:220:7)
    at emitNone (events.js:67:13)
    at Walker.emit (events.js:166:7)

I installed wat as root but am using it as my own user. Does wat try to cache in its install location? (If so, requesting $XDG_CACHE_HOME/wat|| ~/.cache/wat instead.)

[wooorm]

@dthree First of all, very nice work! From what I tried, wat was really useful and I plan to use it in my flow in the future 👍

I found some funky things going on with mdast. I probably have some weird documentation preferences, so I can imagine that having to do with it. Let me know if you have suggestions regarding that!

[dthree]

@anko aah I see what happened. 99% of the writes go to a temp dir - that write that errored there is something I was going to fix, didn't realize it would create that problem. Should be handled today! Anyway, if you run it as root for now, you should be able to make it through the rest of the tour :)

[dthree]

@wooorm thanks!!

On mdast, yeah I saw that. I just added like 10 more libs yesterday, so I have to go through and tune the autodoc generator to hit more edge cases. The main sit is recognizing what is and isn't an API syntax declaration.

I'll probably end up fine-tuning about 30 or 40 libs before I release it.

Happy you find it useful though, and suggestions are accepted!

[wooorm]

👍

[dthree]

@anko just did a mongo refactor that migrates all writes to the temp directories. I think I got everything. Would you mind re-installing and trying the tour again?

[dthree]

@wooorm I managed to clean up the autodoc response of mdast a bit. Still a few challenging quirks, I think though. Would you mind checking it out and telling me what you see wrong with the generated docs?

[wooorm]

Looks better, but still some problems, I listed some points I found in GH-23.

[anko]

@dthree Aaa, now I get

$ wat tour

  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                                                                                                                                                                                                                              |
  |  Welcome to Wat. Let's look up how to use Javascript's "array.slice()" method.                                                                                                                                                                                                                                                               |
  |                                                                                                                                                                                                                                                                                                                                              |
  |  Type "js array slice" and press [enter].                                                                                                                                                                                                                                                                                                    |
  |                                                                                                                                                                                                                                                                                                                                              |
  └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

? js array slice

  Sorry, there's no command like that.


  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                                                                                                                                                                                                                              |
  |  This pulled up a rapid description of the ".slice" command, and a usage example.                                                                                                                                                                                                                                                            |
  |  This is the hallmark of wat - just the data you need, and nothing more.                                                                                                                                                                                                                                                                     |
  |                                                                                                                                                                                                                                                                                                                                              |
  └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘


  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                                                                                                                                                                                                                              |
  |  Now, let's see what content wat has. Press [tab] twice.                                                                                                                                                                                                                                                                                     |
  |                                                                                                                                                                                                                                                                                                                                              |
  └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

? 

Anything I enter says "there's no command like that".

Is there perhaps a cache I haven't deleted that's giving me a dirty install?

$ jq '.version' < /lib/node_modules/wat/package.json
"0.1.31"

[dthree]

Did you just do a fresh install? Try the index command:

? index"

This should re-index you.

But I'll check that out. I need to make a nuke command or something that destroys the local files.

[dthree]

@wooorm @anko @tomByrer @octalmage @defel @Qix- just finished the Wiki docs for adding auto doc content to Wat. Adding a library should be incredibly easy and take 10 minutes or less, so I want to make sure my docs are intuitive and reflect that.

If you guys are able to, would you mind reading this Wiki and seeing if you can successfully do a PR on a new doc set? You can just pick any library you love. If anything's confusing, I'd like to know now, not when I release it :)

https://github.com/dthree/wat/wiki/Docs-|-101

Thanks!! (and btw I'm thanking all contributers directly on the readme)