New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/build: flesh out READMEs #21285

Open
bradfitz opened this Issue Aug 2, 2017 · 1 comment

Comments

Projects
None yet
4 participants
@bradfitz
Member

bradfitz commented Aug 2, 2017

@andybons had some ideas for improving our README.md files in https://golang.org/cl/52856

I feel like this should be a block that one can keep within the README since it’s useful to have it automatically update, but the author should also be able to update the contents outside the block.

So, do that. And also go through each README.md and add useful content if warranted.

And/or look at @davecheney's https://github.com/davecheney/godoc2md and maybe use that too, to put more of the package doc into the Markdown. I was only able to get the synopsis easily, but it'd be nice to have the whole package comment.

(I don't need to see the API, though. That's what godoc.org is for.)

@dmitshur

This comment has been minimized.

Member

dmitshur commented Aug 2, 2017

I was only able to get the synopsis easily, but it'd be nice to have the whole package comment.

You can use go/doc package for that. Its API is not pleasant to use, but it works.

See https://godoc.org/go/doc#Package.Doc, that's the whole package comment, not just synopsis.

(Edit: If you need help going from *build.Package to *doc.Package, you can look here, but that's probably not the cleanest code for doing it. It's functional though. If someone can suggest an improvement, I'd be happy.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment