Skip to content
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.

Sign up for GitHub

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

Jump to bottom

x/build: flesh out READMEs #21285

Closed
bradfitz opened this issue Aug 2, 2017 · 2 comments
Closed

x/build: flesh out READMEs #21285

bradfitz opened this issue Aug 2, 2017 · 2 comments
Labels
Builders x/build issues (builders, bots, dashboards) Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
Go Release Team
Milestone
Unreleased

Comments

@bradfitz
Copy link
Contributor

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.)
@bradfitz bradfitz added Documentation NeedsFix The path to resolution is known, but the work has not been done. labels Aug 2, 2017
@gopherbot gopherbot added this to the Unreleased milestone Aug 2, 2017
@gopherbot gopherbot added the Builders x/build issues (builders, bots, dashboards) label Aug 2, 2017
@dmitshur
Copy link
Contributor

dmitshur commented Aug 2, 2017 •
edited

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.)

@andybons andybons removed their assignment Sep 18, 2019
@dmitshur dmitshur self-assigned this Jun 17, 2022
@cagedmantis cagedmantis added this to In Progress in Go Release Team Jun 21, 2022
@dmitshur
Copy link
Contributor

[...] it’s useful to have it automatically update, but the author should also be able to update the contents outside the block.

That was implemented in CL 300229; I forgot about this issue otherwise would've included a "Fixes" line in it, so I'll close this now. (I've considered other README improvements that were mentioned here, but I think by this point it'll be better to file new issues if there's a specific need.)

Go Release Team automation moved this from In Progress to Done Jun 21, 2022
@golang golang locked and limited conversation to collaborators Jun 23, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Builders x/build issues (builders, bots, dashboards) Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
Go Release
Archived in project
Go Release Team
Done
Milestone
Unreleased
Development

No branches or pull requests
4 participants
@bradfitz @andybons @dmitshur @gopherbot