0.9.0: developer docs

[jonschlinkert]

These are questions that we should try to answer in the docs: (is there anything you'd like to know? please add your comments below!):

• what does verb do / how does it work?
• what makes verb work? (what are the moving parts)
• what can I create with verb?
• how do I customize verb?
• how can I store config values?
• how do I make a *? (helper, plugin, middleware, template, generator, linter)

cc @doowb

[ericclemmons]

I'm trying to user verb today and, despite being quite the tooling fan, am struggling to know how to use it.

Before a major docs rewrite, would it be possible to have an exhaustive README.md with almost every type of feature leveraged?

So far, I've seen things like apidocs, [path-to-something][] without links, badge("furry") (none of my business), etc.

But it's mostly doing excavations in other's repos vs. just following a visible, working example.

TBH, I just want to run verb or verb --watch, write a README, and be able to use that across multiple projects.

Sorry if this comes off the wrong way. I'm excited about this project, but I think I caught it a bit ahead of it being ready for me :)

[jonschlinkert]

despite being quite the tooling fan, am struggling to know how to use it.

sorry about that! this will be resolved very soon, but in the meantime if it's any consolation I would be happy to give you a personal walkthrough. you would get a chance to decide if verb is something you want to use, and I would get honest feedback. it's up to you, but I'd be happy to do it

Sorry if this comes off the wrong way

no, this is good honest feedback, thank you.

In case it helps, with 0.9.0 we finally have a locked down API and we know what verb will do going forward. We have API, CLI and user docs on the way.

Before v0.9.0, verb had several major (necessary) refactors. I didn't want to write extensive docs before the API was completely baked - I wanted to spend that time fixing verb to be the documentation system I've always wanted. Despite all of those changes, verb plays a big role in my personal productivity, and now that the API is crystallized we can finally start showing other devs how to use verb to do the same.

[jonschlinkert]

badge("furry") (none of my business), etc.

lol I just saw this comment. It's one r. but hey, helpers and templates are customizable, so you can do badger('furry') if you prefer templates that need to be shaved first.

[ericclemmons]

Heh, I was glad you caught that ;)

Anyway, yes, I'd <3 to have a better understanding of how to use it. This would probably help me the best:

would it be possible to have an exhaustive README.md with almost every type of feature leveraged?

The project makes sense, but I don't think I have a need to do anything outside of the built-in helpers (yet). I'm just struggling to piece together all the different sources to know what all can I do out of the box?

(I'm about to open-source ~6 new projects, so I was hoping to copy/paste .verb.md to them all :))

[tomByrer]

• What changed in v0.9.0?

(CHANGELOG is a bit bare ATM)

[jonschlinkert]

It's not published yet

[aredshaw]

Would you like help with some of the documentation? I am learning to do REST API docs and I would love to help if I can.

[jonschlinkert]

Would you like help with some of the documentation? I am learning to do REST API docs and I would love to help if I can.

We'd love some help! We would be willing to teach you the API and walk through the code if that helps.

(as a side note, we're getting ready to push up some major changes to verb - mostly to simplify the code, cut down on deps, and improve performance, but the API won't change much)

[aredshaw]

I was trying to install and use Verb using README.md in order to document it better. Here are some questions I have. Keep in mind I am a novice, but some other users might be as well.

1. I see that many of the packages are deprecated. I tried to install it and get it working using the Readme. The one place I am stuck is where it says:

Next, just add a .verb.md markdown template to your project and run verb in the commandline.

I was not sure what this meant. I made a copy of a blank readme file (from this), named it .verb.md, and put it in another project folder I have.

2. The line that says:

var verb = require('verb');

This looks like something that should be put in a website's javascript. Where would I put this line?

3. I typed in "verb" in my command line after installing it and got
   module.js:550 throw err; ^
   Are you still working out the kinks?

4. And last for now, I see you have a list of methods, but what are the endpoints for this API?

[aredshaw]

I am already working on the readme file, trying to answer the questions addressed above. When I get more feedback from my previous questions, I can add more. I cannot get it to work yet myself.

I like the examples of what it can do from the projects listed.

[tunnckoCore]

Heya @aredshaw! I can help here, because i have a huge knowledge of everything by Jon and Brian.

The thing is that the latest stable Verb release is not what you see in the master branch README.
Check out the dev branch readme. It still may be not good enough too, but is at least where we should start.

The whole thing is that you need to install it more specifically.

npm install -g verbose/verb#dev

This will install it from github's dev branch instead of the latest npm version.
I'm not sure that the latest verb on npm is working or at least is doing what should be expected. We (me & more advanced users and @jonschlinkert & @doowb themselves) all use the dev branch for few years now. All the latest building blocks (few hundreds) are used in Verb's dev branch. We are using it for years, so it can be considered "stable" and "official" in my opinion.

However. The most common use case of Verb is generating READMEs, but is not limited to that, it's hugely configurable and extendable programmatically. ANd here is where var verb = require('verb'); comes. This can be written in verbfile.js (the default config file) or any other javascript file and pass it to --config flag (actually I'm not sure what was the flag ;d).

The easiest usage is installing it and then install verb-generate-readme and running verb - it will detect that there is no .verb.md file and will generate some for you, plus will write some default configuration in your package.json as verb field there. The .verb.md is nothing more than just a template for your README.md file. It uses a hugely enhanced and flexible template engine behind the scenes and gives you a lot of helpers and functions - eg. getting code comments and generating API docs (basically mostly all of the helpers in https://github.com/helpers and https://github.com/helpers/handlebars-helpers are included and can be used in .verb.md template). The verb-generate-readme is in turn, generally, a package that gives Verb few common templates & layous for READMEs. You can also define verb.layout field in your package.json to empty (i use this one in all my repos), then it will not use the builtin ones, but what is in you .verb.md file. Micromatch uses the default built-in layout.

All the READMEs of 90% of all packages and repos of me, Jon & Brian for the last couple of years are generated by Verb and are real-life examples of what Verb and Verb-Generate-Readme are doing in combination.

https://github.com/micromatch/micromatch README is a phenomenal example of how crazy it can go :D

---

@jonschlinkert when v0.9 will finally be published? ;d It really was few years, haha.. How time passed... It's proven that it is working quite well for all of us and can dev branch be just published. Then we can continue fresh with updates & docs and new PRs and refactors (if there is new refactors).

[aredshaw]

I've made some changes to the README.md for the dev branch, but I'm not sure how to push something to a dev branch. I get permission denied when I try.

My changes are mostly link fixes, or deleting links where the reference no longer exists.

[doowb]

@aredshaw the process is usually like this (I'm going to list some git commands. If you're using a GUI, there are probably similar commands):

• fork the repository (which it looks like you've already done).
• add a remote for your fork (I usually have origin already used for the main repository, so I'll use my name as the new remote)

  $ git remote add aredshaw https://github.com/aredshaw/verb.git

• make a branch from the dev branch

  $ git checkout -b my-branch-name dev

• make your changes and commit them to your branch

  $ git add .
  $ git commit -m "changes that I made"

• push the branch up to your fork

  $ git push aredshaw my-branch-name

• submit a pull request through GitHub from your fork to the dev branch here

If you didn't make the changes on another branch and just used the dev branch, that's fine too. You can still push the dev branch to your fork and sumit a pull request from there.

I hope this helps.

[aredshaw]

It worked! That was super helpful. Thanks.