search

zeke / package-json-to-readme

Generate README.md from package.json contents
npm.im/package-json-to-readme
385 stars 51 forks source link

use `update-readme` to power version 3.x #19

Open billiegoose opened 7 years ago

billiegoose commented 7 years ago

@zeke: package-json-to-readme has served me well for the last few years, but I really need to dust it off and make some improvements. It's currently useful for getting a README started but after that you're on your own. I would love to borrow some of the concepts from mos and jsmd to help keep READMEs up to date over time.

I am in the same place. I have a README template I use in my project boilerplate, but whenever I make improvements, it only benefits new modules I write. There's not an easy way to update my existing projects to a new, improved README.

mos and projectz are both really cool - but both involve changing the way you write READMEs and adding extra markup in HTML comments. My boilerplate is a frankenstein of package-json-to-readme, mos, and projectz and it's ridiculous.

I've started a Github org called update-readme with the goal of updating README files without the constraint of requiring additional markup. I feel that having the tool work with existing README files as they are found in the wild is important to frictionless adoption. I'm using a very different approach than the hogan template rendering that package-json-to-readme uses, but would love to see package-json-to-readme v3.x implemented as a collection of update-readme plugins. (Disclaimer: I'm not satisfied with the plugin authoring API. As it stands, I think it exposes too much implementation detail. But since I'm implementing it, that's actually convenient.) Right now it only has two plugins, one for name & description and one for license. Both of which I wrote yesterday.

Thoughts? Feedback? Hopes? Fears? Dreams?

zeke commented 7 years ago

would love to see package-json-to-readme v3.x implemented as a collection of update-readme plugins

👍 I'm all for it.

goal of updating README files without the constraint of requiring additional markup

I like this idea. For example, an update-readme-dependency-list plugin could look for a heading like ## Dependencies and inject an updated dependency list into the space between it and the next H2 element.

billiegoose commented 7 years ago

Yes, exactly! If you're cool with it, I'll fork package-json-to-readme and create a new v3.x branch/pull request.

zeke commented 7 years ago

@wmhilton I've added you as a collaborator. Feel free to move this repo to an org.

billiegoose commented 7 years ago

:D I need to launch a kickstarter so I'll have time for all the things I want to work on. (Most of which, unsurprisingly, are projects to automate things so I'll have more time for my projects...)

img

billiegoose commented 7 years ago

This is going to happen. I've just got sidetracked last week developing https://github.com/wmhilton/beautify

zeke commented 7 years ago

Thanks for the update. :)

billiegoose commented 7 years ago

I have pushed a branch! I called it 'next' because I'm not very imaginative.

My approach is to substitute hogan with update-readme incrementally. It uses update-readme for name, description, installation, and license, but still uses hogan for the other parts. Since the update-readme API isn't frozen yet, I'm using npm link and developing the plugins in tandem. So this branch might work or might not at any given point. Right now, it works on my machine. :)

Any thoughts on how to enhance the Travis badge? I know I've seen modules that do all sorts of badge.... I am thinking it would be nice to have a single update-readme-badges plugin than 50 update-readme-X-badge plugins.

This week I got sidetracked developing https://github.com/wmhilton/download-with-webtorrent-button

dawsbot commented 7 years ago

@wmhilton Instead of doing an npm link and hoping that update-readme will work at any given time, shouldn't you be able to pin the version in the package.json that package-json-to-readme is relying upon? That would involve first adding it as a dependency (I don't see the update-readme package as a dep in the next branch). After adding that dep, remove the ^ which is automatically added by npm so that instead of a range of versions, you rely on the single one. This should be all it takes to have reproducible installs.

billiegoose commented 7 years ago

@dawsbot I know what I'm doing... I'm not trying to have reproducible installs. That would kinda be a needless burden since this is still in an early alpha stage. If it was just update-readme then sure. But it's update-readme plus all the plugins, none of which are on npm yet. Because I'm kind of writing the plugins for package-json-to-readme, rather than the other way around, I'd rather move fast and break things than publish to npm after every commit with a major version bump because of breaking changes.

Did you actually want to try out the next branch? If so, that changes everything, and I'll totally add in the dependencies. I was just adhering to the idea that "publish early, publish often" is more important than "publish flawless code you'd be proud of".

zeke commented 7 years ago

update-readme-badges plugin

sounds good to me.

Wanna open a PR with the work you've done so far?

billiegoose commented 7 years ago

That's a great idea. Um... I haven't touched the code in a bit -- somehow I got sidetracked and starting writing in assembly code -- but after I get a chance to refresh myself on where the code is at I'll make a PR