verbose / verb-generate-readme Goto Github PK
View Code? Open in Web Editor NEWGenerate your project's readme with verb. Requires verb v0.9.0 or higher.
License: MIT License
Generate your project's readme with verb. Requires verb v0.9.0 or higher.
License: MIT License
Actually, not big deal, but just noticed. And pointing it here, cuz can't remember where it comes from.
I'm talking for the author section that has github and twitter links with your username.
I'm thinking for global generators options, so it can't be simple templates
property in ~/data-store/verb.json
config, because verb may need more than one generator, so it could be something like that
{
"generators": {
"readme": {
"templates": "layouts/*.md",
"includes": "includes",
"badges": "badges"
}
}
}
or full paths/globs to dirs
for this generator
I'm thinking it can be easy and quick addition.
For example
/home/charlike/dev
- foo
- .verb.md
- bar
+ project
- index.js
- LICENSE
- test.js
+ aaa
+ bbb
- ccc
- baz
- qux
I'm always trying to low the dotfiles and such things and in same time I realize why they are (good and) need - for the contributors. But actually we can agree on that in most cases they don't have job with verb - meaning, only in rare cases they can fix some documentation bug or something.
That's why i'm suggesting to allow verb.md lookup in upper directories. Then we can just have one .verb.md in our home dir.
Buuuut, yea, this may cost time. But in another hand, we can save it globally.
edit: in short: in anyway it's your (owner) job to regenerate the docs and publish a new version.
just noticed that, not sure from which day is, but i believe it is from recent update to 0.4.2
. Also seen that you updated few libs last few days and you don't have that problem. Ideas? I didn't change anything
It seems, that it happend around 20 feb? I believe my last readme update using 0.4.1
is from 20 feb.
markdown isn't changed from that in last months
## License
{%= copyright({ start: 2016, linkify: true, prefix: 'Copyright', symbol: '©' }) %} {%= license %}
We've got several projects with the same setup generating the readme, and now on a Windows 7 Enterprise system we get this error (using git bash):
$ verb
[11:12:28] starting verb
[11:12:29] √ running tasks: [ 'verb-generate-readme' ]
[11:12:29] starting verb.readme
[11:12:29] starting verb.readme:default task
[11:12:29] starting verb.readme:readme task
Error: no parsers registered for: "
>"
at parse (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\snapdragon\lib\parser.js:473:15)
at Parser.parse (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\snapdragon\lib\parser.js:477:24)
at Snapdragon.parse (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\snapdragon\index.js:122:28)
at expand (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\expand-reflinks\index.js:14:24)
at C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\verb-reflinks\index.js:26:15
at DestroyableTransform._transform (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\gulp-reflinks\index.js:8:22)
at DestroyableTransform.Transform._read (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\readable-stream\lib\_stream_transform.js:182:10)
at DestroyableTransform.Transform._write (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\readable-stream\lib\_stream_transform.js:170:83)
at doWrite (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\readable-stream\lib\_stream_writable.js:406:64)
at writeOrBuffer (C:\Users\art\AppData\Roaming\npm\node_modules\verb-generate-readme\node_modules\readable-stream\lib\_stream_writable.js:395:5)
Using latest versions of node(6 lts) npmjs verb and verb generate-readme
cc @phun-ky
Because if some greenkeeper update fails it shows red badge on the readme and I think this isn't good. Users may think the master branch and published release fails, which isn't correct. It's not good for reputation of the package/repository, so I recently changed it in my readmes.
https://img.shields.io/travis/node-minibase/minibase.svg
https://img.shields.io/travis/node-minibase/minibase/master.svg
edit/updated
> verb readme
path.js:7
throw new TypeError('Path must be a string. Received ' + inspect(path));
^
TypeError: Path must be a string. Received undefined
at assertPath (path.js:7:11)
at Object.dirname (path.js:1324:5)
at Liftoff.run (/Users/Vaughan/nvm/versions/node/v6.0.0/lib/node_modules/verb-cli/bin/verb.js:133:27)
Super weird... as always :D
{%= ifExists([process.cwd() + '/.verb.head.md'], include(process.cwd() + '/.verb.head.md')) %}
Fails by saying that it cannot include .verb.head.md
beacause it's not found.
~~I forgot, where is exactly this helper? ~~
Found it, it's https://github.com/verbose/verb-repo-helpers.
edit: Oooh. Got it, it's because include
is also called, no matter of the if
condition.
/cc @doowb @jonschlinkert
I'd like a layout like common
but without the badges in the head
partial.
This is for projects not published to npm
but still have the full about section, TOC, and name and description.
I'm putting this here to remind myself to create it and get feedback on if it's necessary and what the name should be. I think it'll look like this:
{%= name %}
> {%= description %}
{%= include('highlights') %}
## Table of contents
{%= include('toc') %}
{% body %}
## About
{%= include('about') %}
I seeing that you are using lowercased contributing.md
from root or from .github
directory and i think you do it that way intentionally. But when it is uppercase and it is in root (not sure if it works same way if it is uppercased in .github dir) it automatically adds one yellow note when you start creating new issue.
For example https://github.com/tunnckoCore/mukla/issues/new
So, my suggestion is to add one more include that is called contributing-guide
for example that tries to access uppercased. Because current templates tries to load contributing.md
and .github/contributing.md
if they exist, and if they exists adds contributing-advice which in my case i use to point to CONTRIBUTING.md in root.
Or if you consider changing it, also would be cool :)
edit: sorry, this may be my worst issue huh.. just not so concentrated ;d
edit2: just see how https://github.com/node-minibase/minibase-create-plugin#contributing section looks for example. It is just pretty similar, but points to uppercased CONTRIBUTING in root, that's all about this issue. ;d
I have a package named: @scope/core
, and when generating the readme, the name of the package in the readme file becomes: scope
, not core
or @scope/core
. How can I get the correct package name in the readme?
I'm not sure how exactly to debug it, but it somewhere in verb-repo-data#L14-17 or repo-utils
the .username()
method, from first glance look.
I've just updated to latest verb#dev and ran verb
on repo which is from organization, not from my own account.
An issue in get-pkg
actually makes this repo to break, see here:
jonschlinkert/get-pkg#4
I have created a PR, but wasn't able to update the whole chain of requirements to get verb-generate-readme ...
Edit: I have found it, as soon as the get-pkg PR is merged, verb-repo-helpers need to be updated, then verb-generate-readme should again work as designed.
@jonschlinkert , @doowb , could you pls verify, thx a lot!
I'm going to major standardizing and my flow would soon be totally automated, crazy and awesome. I'm using the "standards" - standard
, semantic releasing with standard-version
(which is almost the same as semantic-release
), and wanna have standard readmes too.
offtopic: What I imagine:
It seems it is missing in badges or anywhere. You may updated it locally :)
I'm trying to move to follow your default readme as much as possible.
Was driving me crazy last few hours 😆 I thought "damn, i'm really stupid guy, why tha heck?!" ;d
Anyway. Sorry for the reports. I know for the upcoming complete refactor of most tools but.. Just to be notified and take it in mind for future. At least all those things are notes for me too.
Simple example:
.verb.md
# {%= repository %}
package.json
{
"name": "@tunnckocore/foo",
"version": "1.0.0",
"main": "index.js",
"license": "MIT",
"repository": "tunnckoCoreLabs/foo"
}
After running verb
it creates README.md with
# tunnckoCoreLabs/tunnckocore
Don't know how and why, but.. Hm. Examples.
Say you have this index.js
and run it with node index.js
const verb = require('verb')
const app = verb()
// we loading all the goodness
app.extendWith('verb-generate-readme')
const view = app.view('foo.md', 'abc {%= name %} zzz {%= foo %} yeah')
app.render(view, { foo: 'qux' }, (err, res) => {
if (err) return console.log(err)
console.log(res.content)
// => 'abc {%= name %} zzz {%= foo %} yeah'
})
It just not works. Pretty strange, since it is working through the cli as we know.
Probably there something is done, that respects the engineOpts
option which we set here.
Anyway, the workaround is to manually use app.setEngine
and set delims
there instead to the engineOpts
option.
const verb = require('verb')
const app = verb()
// we loading all the goodness
app.extendWith('verb-generate-readme')
app.setEngine('md', app.getEngine('.*'), { delims: ['{%', '%}'] })
const view = app.view('foo.md', 'abc {%= name %} zzz {%= foo %} yeah')
app.render(view, { foo: 'qux' }, (err, res) => {
if (err) return console.log(err)
// works now
console.log(res.content)
// => 'abc baaaw zzz qux yeah'
})
Just opening this issue to note this. It's not exactly a bug, but would be good to be updated, because we should be able to use them programmatically the same way as with through CLI.
related to https://mobile.twitter.com/tunnckoCore/status/1021995363643924481
/cc @doowb @jonschlinkert 😺 👋
Hi,
how can I set custom config for e.g. twitter.username
, I tried:
"verb": {
"run": true,
"toc": false,
"data": {
"twitter": {"username": "waltherstefan"}
},
...
But this is not working as expected ...
Regards
Stefan
it's 2017 now, haha. And because I just updated one package that is from 2015 I set start
year of the copyright helper to 2015 and it outpus
Copyright © 2015, 2017, Charlike Mike Reagent. Released under the MIT license.
when the year is set to 2016 in start
option it is correct (with dash)
Copyright © 2016-2017, Charlike Mike Reagent. Released under the MIT license.
So I believe it should be
Copyright © 2015-2017, Charlike Mike Reagent. Released under the MIT license.
when
## License
{%= copyright({ start: 2015, linkify: true, prefix: 'Copyright', symbol: '©' }) %} {%= license %}
I'm experiencing some strange bug with that one. Do you have some ideas?
Im just setting <!-- toc -->
as needed, run verb, then generated table of contents not includes the headings generated from apidocs
which actually, is links. I have some heading on same level after the apidocs and it is included.
It's not markdown-toc
related, i checked.
Example
Name | Description | Downloads |
---|---|---|
micromatch | Highly optimized wildcard and glob matching library. |
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.