dthree / wat Goto Github PK

View Code? Open in Web Editor NEW

493.0 13.0 25.0 783 KB

Instant, central, community-built docs

License: MIT License

JavaScript 86.61% HTML 13.39%

wat's Introduction

Wat

Rebelliously practical docs. For and by the community. Wat.

Finally, community-built cheat sheets for every coder, targeting any framework, in any language.

At the tip of your fingers.

Wat is an interactive app built to drastically reduce time spent searching for syntax and code usage questions. Wat aggregates project APIs, readmes, code snippits, usage samples and practical documentation across any language or libary, and makes this data ridiculously accessible from the one tool every developer uses: the CLI.

Wat was designed for ease. It takes you:

20 seconds to install
5 minutes to master
15 minutes to contribute

Notice

This is now an OPEN Open Source project. I have not able to invest enough time into completing Wat and so am looking for volunteers who would like to take the project over and push it to completion. If you are interested, shoot me a note.

Introduction
Install
Learn
Contribute
What's on Wat
FAQ
License

Made by dthree with ❤️ and a little secret sauce.

Introduction

Wat is scheduled for imminent release!

Want to contribute and make it happen? Email me or join the Gitter channel.

Want to try it right now?

$ npm install -g wat
$ wat tour

Wat covers everything

Wat provides the only community-based, centralized source of syntax cheat sheets for every language and every major framework and library. If it has an API and is used by the community, it's supported here!

It's smart

Wat combines indexes, edit-distance algorithms, auto-completion and common sense to make sure you get what you asked for. It auto-updates when the community adds content, and optimizes its performance based on the content you use most.

It shreds red tape like a frisky cat

Wat's content is not perfect, it isn't formal and it isn't pedantic. Wat doesn't aim to provide letter-perfect, official documentation for languages. Work like that is in good hands.

If you're building a web browser, refer to W3C for specifications. Wat is targeted for the 99.99% of us who have the basic familiarity with a library and simply need to look up API or usage samples.

Install

npm install -g wat

np-what? Oh, isn't that Node? I don't do Node.

Learn

wat tour

Contribute

Contributing is easy!

Get started here, and help spread the word!

Wat is like a giant, friendly snowball that's somehow caught fire. The bigger the community, the better it gets. ❄️ 🔥

Future

If Wat gets sufficiently adopted by the community, I'll make a web-based version as well.

Same data, new fancy interface.

Projects now documented on Wat

Languages

JS (some of it), Node

Javascript Libraries

D3

Node.js Libraries

Chalk, debug, download, got, MDAST, mkdirp, Node HTTP Proxy, Node Inspector, Pageres, request, RobotJS, Screenful, Vantage, Vorpal

FAQ

Why Wat?

Because wat is forgetting the syntax to splice an Array for the 10th time.

Because wat is having to search js splice an array, sift through W3Schools and MSDN results, Command + Click three Stack Overflow tabs, close the first one, digest the second and then scroll to the answer to remember... again.

Because I would rather just type:

wat js array splice

License

MIT

wat's People

Contributors

Stargazers

Watchers

wat's Issues

Failed to install on Windows

Hello you have an intresting project that would be awesome for me to contribute. Though I am having trouble installing it or installing it correctly as seen here:

26980 verbose stack Error: ENOENT, open 'C:\Program Files\nodejs\?.cmd'
26980 verbose stack     at Error (native)
26981 verbose cwd C:\WINDOWS\system32
26982 error Windows_NT 6.3.9600
26983 error argv "C:\\Program Files\\nodejs\\\\node.exe" "C:\\Program           Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install" "-g" "wat"
26984 error node v0.12.7
26985 error npm  v3.2.2
26986 error path C:\Program Files\nodejs\?.cmd
26987 error code ENOENT
26988 error errno -4058
26989 error enoent ENOENT, open 'C:\Program Files\nodejs\?.cmd'
26989 error enoent This is most likely not a problem with npm itself
26989 error enoent and is related to npm not being able to find a file.
26990 verbose exit [ -4058, true ]

Any ideas of why I am receiving these errors? Would it be more appropriate to put this issue on npm?

Wat exits with non-zero upon ^C

Upon exiting wat with CTRL+C, it returns non-zero (exit code 130 to be exact). It should probably exit with 0 💃

CLI REPL requires two ^C to exit

Hitting CTRL+C once puts wat into a weird, hung state and requires a second CTRL+C to actually exit.

`wat tour` eventually has problems

Here's one issue that I got past---it appears that there's supposed to be stripColor but it's not there? I just went with supportsColor and the tour continued.

? chalk

  enabled  styles  supportsColor  readme/


  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  Nice. That last tab you did shows what's in Chalk. The green items are methods, blue are properties, and the rest are         |
  |  docs, such as Chalk's readme on Github.                                                                                       |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘


  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  Take a look at what's in "stripColor". You've typed half of it already.                                                       |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

? chalk stripColor

? Did you mean: chalk supportsColor

This was also kind of weird because I hadn't already typed half of it (assuming "it" refers to "stripColor").

The problem I'm stuck on now is the grepping option:

? github dthree wat
? Results: 1. GitHub - dthree/wat: Instant, central, community-built docs
     Instant, central, community-built docs. Contribute to wat development by creating  an account on GitHub....
:

  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  You can also run this with "gh ..." or "readme ...".                                                                          |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘


  ┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
  |                                                                                                                                |
  |  Wat can also grep things! Let's have some fun:                                                                                |
  |                                                                                                                                |
  |  Run "gh awesome node -l | grep simple | less" to find some simply awesome things.                                             |
  |                                                                                                                                |
  └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

? gh awesome node -l | grep simple | less

  Missing required option. Showing Help:

  Usage: grep [options] <pattern> [files...]


  Grep (POSIX) implementation.

  Options:

    --help                    output usage information
    -i, --ignore-case         ignore case distinctions
    -w, --word-regexp         force pattern to match only whole words
    -s, --no-messages         suppress error messages
    -v, --invert-match        select non-matching lines
    -m, --max-count <num>     stop after num matches
    -b, --byte-offset         print the byte offset with output lines
    -n, --line-number         print the line number with output lines
    -H, --with-filename       print the file name for each match
    -h, --no-filename         suppress the file name prefix on output
    -q, --quiet               suppress all normal output
    --silent                  suppress all normal output
    --include <file_pattern>  search only files that match file_pattern

?

(Awesome tool, BTW! The only other thing I've noticed is that navigating my cursor around a line of command I've typed causes the text to flicker and the cursor to jump around. This might be an underlying issue; if it's relevant / fixable, please let me know and I'll open a separate issue for it.)

Proxy Issues?

When I attempt to pull up certain commands in Wat, such as vantage auth or vantage firewall reject, I get this:

Unexpected Error:  { [Error: connect ECONNREFUSED]
  code: 'ECONNREFUSED',
  errno: 'ECONNREFUSED',
  syscall: 'connect' }

My internet is going via an HTTP proxy set in the OSX system settings, and I'm guessing that this may be the issue. Any thoughts? (If it's just a lack of implementation, and you point me to the code in question, I may be able to try some stuff out.)

SyntaxError: Use of const in strict mode.

Command: $ wat css animation
Path: /node_modules/wat/bin/index.js:5
Error:

const uh = require("./../");
^^^^^
SyntaxError: Use of const in strict mode.
    at exports.runInThisContext (vm.js:73:16)
    at Module._compile (module.js:443:25)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:501:10)
    at startup (node.js:129:16)
    at node.js:814:3

Node version: v0.12.6

`?`

Typing a single question mark (?), while not necessarily idiomatic, is sometimes used in command line tools to display help. In wat, it's implemented as a quick way to throw an error and return to the shell. This design decision might best be reviewed. Error message follows:

$ wat
? ?
readline.js:924
            throw err;
            ^

SyntaxError: Invalid regular expression: /(?)/: Invalid group
    at new RegExp (native)
    at forEachInIndex.filter.okay (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:164:19)
    at traverse (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:138:17)
    at traverse (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:143:13)
    at traverse (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:143:13)
    at Object.forEachInIndex (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:148:5)
    at Object.search (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/clerk/clerk.js:154:10)
    at CommandInstance.<anonymous> (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/dist/vorpal/catch.js:153:33)
    at EventEmitter.session.execCommandSet (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/node_modules/vorpal/lib/session.js:432:24)
    at EventEmitter.vorpal._exec (/Users/mg/.nvm/versions/node/v4.1.2/lib/node_modules/wat/node_modules/vorpal/lib/vorpal.js:798:18)

Snippit maintenance / automatic doc generation

For intro comments, see 419654c

Node Download links

Node download links refers to node 0.12.7 under the faqs.

I think that these should be updated to 4.2.0.

What do you think?

Latest version of wat fails

Looks like a module was introduced that's causing problems?

This is right after a fresh npm i -g wat.

Textual error:

module.js:338
    throw err;
    ^

Error: Cannot find module 'unzip'
    at Function.Module._resolveFilename (module.js:336:15)
    at Function.Module._load (module.js:286:25)
    at Module.require (module.js:365:17)
    at require (module.js:384:17)
    at Object.<anonymous> (/Users/qix/.nvm/versions/io.js/v3.1.0/lib/node_modules/wat/lib/clerk.js:10:15)
    at Module._compile (module.js:430:26)
    at Object.Module._extensions..js (module.js:448:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Module.require (module.js:365:17)

wat should support a --version flag

I was writing a bug report and wanted to include the version of wat I had installed.
This is what happened:

 $ wat --version

  Sorry, there's no command like that.

Goodbye!

wat tour throws error at clerk.js 'error saving to the local filesystem', undefined is not a function

$ npm install -g wat
C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\wat -> C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\bin\index.js
[email protected] C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected]
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], collapse-white-space@1
.0.0, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected].
0, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], c
[email protected])
├── [email protected] ([email protected])
├── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], tunnel-agent@
0.4.2, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected].
5, [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], [email protected], h
[email protected])
├── [email protected]
├── [email protected]
├── [email protected]
└── [email protected] ([email protected], [email protected], [email protected], [email protected], [email protected], babel-runtime@
6.5.0)

$ wat tour
?

  -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  |                                                                                                                                                                                                                                       |
  |  Welcome to Wat. Let's look up how to use Javascript's "array.slice()" method.                                                                                                                                                        |
  |                                                                                                                                                                                                                                       |
  |  Type "js array slice" and press [enter].                                                                                                                                                                                             |
  |                                                                                                                                                                                                                                       |
  |  (You can exit using [control] + c at any time.)                                                                                                                                                                                      |
  |                                                                                                                                                                                                                                       |
  -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

? js array slice
C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\clerk\clerk.js:368
      this.log('Error saving to the local filesystem: ', e);
           ^
TypeError: undefined is not a function
    at Object.file (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\clerk\clerk.js:368:12)
    at C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\clerk\clerk.js:338:19
    at Request._callback (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\dist\util.js:573:11)
    at Request.self.callback (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\node_modules\request\request.js:199:22)
    at Request.emit (events.js:110:17)
    at Request.<anonymous> (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\node_modules\request\request.js:1036:10)
    at Request.emit (events.js:129:20)
    at IncomingMessage.<anonymous> (C:\Users\mohamed.eltuhamy\AppData\Roaming\npm\node_modules\wat\node_modules\request\request.js:963:12)
    at IncomingMessage.emit (events.js:129:20)
    at _stream_readable.js:908:16

Mention Dash

It seems that Dash is trying to solve a similar problem. Maybe write a little comparison?

Trying to create new docs - wont index

Hi,

I need a jump-start again.

I am trying to create new documentation for protractor. As there are no good api-docs for protractor in markdown-format on github, I want to paste them hand-crafted from angular.github.io/protractor to the docs/ folder.

What I have done:

create no subfolder docs/protractor
create two files: docs/protractor/element/all/index.md and docs/protractor/element/index.md
copied config.json from docs/js to docs/protractor and edited it to contains both functions 'element' and 'element/all'
run indexin wat -> nothing happens
run gulp index on shell -> nothing happens

What have I exactly to do, to add this new docs?

For me it looks on the first view exactly like the js doc. The files config/config.json and config/index.json were also updated automatically by index command.

For clarity you can see the wip here: https://github.com/defel/wat/tree/protractor-docs/docs/protractor

mdast documentation

Spin-off from GH-15.

Some points I walked into:

I’m using function foo(...) and the like for user-defined functions, e.g., function attacher(mdast[, options]), these are still visible in was (e.g., for autocompletion), that seems a bit superfluous;
wat mdast process doesn’t show the list of parameters, it ends at Parameters and doesn’t show the rest;
E-mail links are mangled to HTML entities, e.g., Written by Titus Wormer\ntit...;
It seems I cannot enter wat mdast fileSet/, for some reason?
Why does wat mdast mdastrc show up? Weird!

P.S. Really cool that it’s possible to search in documents, e.g., what mdast man mdastnode7 delete works great 😄.

XO standard

I noticed the readme wanted to be XO compliant. I went ahead and started but it looks like it's going to be a hefty job.

If someone would like to jump in and help complete it, that'd be great :) I can't devote much more time to it, though I got rid of most of the errors and configuration.

Gulpfile.js is either going to need to be ES2015 compliant or XO is going to need a way to look at comments to negate the esnext configuration value.

// @sindresorhus

GitHub search dies horribly with `ReferenceError: attacher is not defined`

 wat 
? github testing123

/Users/Ian/gg/timesync-node/node_modules/wat/dist/spider/github.js:36
            var md = mdast().use(stripBadges).use(attacher);
                                                  ^

ReferenceError: attacher is not defined
    at /Users/Ian/gg/timesync-node/node_modules/wat/dist/spider/github.js:36:51
    at Request._callback (/Users/Ian/gg/timesync-node/node_modules/wat/dist/util.js:542:11)
    at Request.self.callback (/Users/Ian/gg/timesync-node/node_modules/request/request.js:198:22)
    at emitTwo (events.js:87:13)
    at Request.emit (events.js:172:7)
    at Request.<anonymous> (/Users/Ian/gg/timesync-node/node_modules/request/request.js:1063:14)
    at emitOne (events.js:82:20)
    at Request.emit (events.js:169:7)
    at IncomingMessage.<anonymous> (/Users/Ian/gg/timesync-node/node_modules/request/request.js:1009:12)
    at emitNone (events.js:72:20)

Add screenshot to readme

(or screencast)

I personally really like it when there’s an image of how a tool looks in the docs, especially when there’s a lot of docs. I also think more people find it useful :)

"Prompt called when mid prompt" a lot

Saw it in the tour immediately after I (also) saw #47. Repro:

sudo npm install -g wat; HEAD when I did this was commit e0d96cc
wat js object defineproperty

Seems reliable.

Kind of a shame; this is a super neat project but apparently not all that usable yet. (Fair enough; it hasn't had a release.) If I can get a pointer to where to start looking for the bug, I might take the time to turn this into a PR with a fix; there's a lot of wat here and I don't really have time to dig into it from scratch.

Cant build local version - problem with 'initClerk'

Hi,

I forked the project and tried to build it local:

npm install
gulp all

and get the following error:

[18:20:21] Using gulpfile ~/code/playground/wat/gulpfile.js
[18:20:21] Starting 'initClerk'...
[18:20:21] 'initClerk' errored after 135 ms
[18:20:21] TypeError: undefined is not a function
    at Gulp.<anonymous> (/home/alexander.weiher/code/playground/wat/gulpfile.js:21:9)
    at module.exports (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/lib/runTask.js:34:7)
    at Gulp.Orchestrator._runTask (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/index.js:273:3)
    at Gulp.Orchestrator._runStep (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/index.js:214:10)
    at Gulp.Orchestrator.start (/home/alexander.weiher/code/playground/wat/node_modules/gulp/node_modules/orchestrator/index.js:134:8)
    at /home/alexander.weiher/code/playground/wat/node_modules/gulp/bin/gulp.js:129:20
    at process._tickCallback (node.js:355:11)
    at Function.Module.runMain (module.js:503:11)
    at startup (node.js:129:16)
    at node.js:814:3

The problem is in the gulp-task 'initClerk' - the start function does not exist:

gulp.task('initClerk', function(){
  clerk = require('./dist/clerk/clerk');
  clerk.start({
    updateRemotely: false
  });
})

// console.log(clerk);
function (app) {
  clerk.app = app;
  clerk.indexer = require('./indexer')(app);
  clerk.history = require('./history')(app);
  clerk.updater = require('./updater')(app);
  clerk.config = require('./config')(app);
  clerk.autodocs = require('./autodocs')(app);
  clerk.prefs = require('./prefs')(app);
  return clerk;
}

Any ideas what I can do?

Wat crashes by creating long tmp path / max call stack exceeded

https://gist.github.com/forivall/e4cf575d0fc8a593f82c

After typing wat tour, I wait for a couple seconds, then the "Maximum call stack size exceeded" error occurs.

linux, iojs 3.2, npm@3. More detail is in the gist terminal log.

"Language?", or some sort of clarity engine

I could see this having a huge impact on other languages, such as C (for instance). Yes, man pages help, but are sometimes much more than what you need (i.e. the common example you use of argument order, etc.).

If I do wat printf, I'm going to get a few different results for a few different languages. Likewise, if I do wat println, I might get a few different options for clarification.

What would be cool to see in Wat is an engine for determining what result the user is most likely looking for, and filling in any missing pieces through continued prompt(s).

For instance, when I do type printf and there are are a few languages - c and php, namely - wat would ask Language?, in which I could respond c.

Further, for the REPL version, it might even be useful to specify what language(s) you're looking for. If I'm a C/JS developer, I will literally never be looking for PHP information. lang c, js or some similar command would be a hint to the clarity engine that I'm going to be looking for language results in either c or js (javascript).

This would be an incredible tool in my arsenal.

Can't use tab completion for selcting themes

I expected to be able to type theme de<TAB> to select the default theme but nothing happened.

Wat tour doesn't appear to work

on Elementary OS, zsh. Node v8.11.3 (npm v5.6.0).
Running wat tour simply prints out two question marks.
However I can run wat js array splice 👍

Hitting tab rapidly in succession causes tabs to be inserted

Title sounds weird, but auto-completion isn't a smooth as it could be. When you hit tab multiple times, the tabs flood the console. Some of them are compensated for, but most of the time they get put in there. It seems wat is handling them correctly, but cosmetically it makes it look all weird.

verb templates

More of an introduction & self-note to use verb's doc templating system as a way to semi-automatically make wat docs.

wat tries to create folders in /usr/lib

I tried installing wat using npm but when I try to start in fails with access denied trying to mkdir /usr/lib/node_modules/wat/.local as part of clerk.scaffold

the paths look vaguely xdgish so maybe $XDG_DATA_HOME is what you want

Exiting could be more intuitive

Not sure if that's a Vorpal UX issue instead.

To exit from wat:

Ctrl-C works
exit works
Ctrl-D on an empty line does nothing (I expected exit as in shell-like behaviour)
q or quit do nothing (I tried q as a reflection / habit from vim/less etc)

Improve search results

Alright so upon first use, specific things like js array splice work great - I love the format and it shows the two things I want the most - syntax, and an example.

I'm not sure if this is just a lack of documentation, or if it's a problem with the search itself, but here are some things that I feel should be pretty rudimentary.

ES6 constructs (not just methods)
Missing Object.defineProperty, etc.
Order of keywords (i.e. splice array)
~~If mis-spellings were silently fixed on the fly, I'd love you forever~~ Nevermind, not sure where I thought they weren't.

DOS→UNIX line endings?

Files seem to have CRLF (DOS-style) line-endings over here. Source code more commonly has LF (UNIX-style) line-endings. (More details on Wikipedia.)

Is there a particular reason for the DOS style? Most editors auto-detect, but I suspect this might be the reason behind e.g. wooorm/mdast#43. I haven't investigated that much though!

"err wrong command" on correct command

So this happened. Got Err... wrong command when the comment was corrected.