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.

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

usability: Need to add documentation for a binary in three different places #20212

Open
kevinburke opened this issue May 2, 2017 · 7 comments

Comments

@kevinburke
Copy link
Contributor

commented May 2, 2017

If I'm shipping a Go binary, generally, I need to add documentation in three different places:

It's a shame that maintainers have to more or less write the same docs in triplicate, and a bad experience for our users when they forget to do so in one or more of the places above.

I also wonder if this discourages contribution, when people get to a Github source code page and the results are clearly not formatted for browsing on that site.

I'm wondering what we can do to ease the burden on maintainers, or make it easy to copy docs from one place to another. I understand that the audiences for each documentation place overlap in parts and don't overlap in other parts, but I imagine some docs are better than nothing. Here are some bad ideas:

  • If a main function has no package docs, but modifies flag.CommandLine, godoc could call flag.PrintDefaults, or call the binary with -h and then print the result. Note the godoc docs linked above manually copy the output from flag.PrintDefaults and it occasionally gets out of sync.

  • If a main function has no package docs but has a README.md, godoc could format README.md and ignore the parts of the markdown spec that we don't want to implement.

  • We could try to get Github to understand and display Go code, the same way it can currently display a number of formats like Restructured Text, ASCIIDOC, Creole, RDoc, textile and others.

@bradfitz

This comment has been minimized.

Copy link
Member

commented May 2, 2017

Didn't somebody once write a tool to auto-generate a README.md file from the Go program's source code?

@ckaznocha

This comment has been minimized.

Copy link

commented May 2, 2017

@bradfitz is this the one you're thinking of godocdown?

I tend to put my docs in doc.go then use godocdown to generate the README to get me started but it ends up feeling a bit redundant with godoc.org.

@bradfitz

This comment has been minimized.

Copy link
Member

commented May 2, 2017

I forget. That might've been the one I saw. I've never used one.

@lrewega

This comment has been minimized.

Copy link

commented May 2, 2017

For going the other way there is: sectioneight/md-to-godoc

@dmitshur

This comment has been minimized.

Copy link
Member

commented May 3, 2017

godoc could ... call the binary with -h and then print the result.

You'd need to do this in a safe execution environment, since you're executing arbitrary binaries (any user code can be inside flag.Usage). I've wanted to add a tab to gotools.org that does that, but it hasn't happened.

We could try to get Github to understand and display Go code, the same way it can currently display a number of formats like Restructured Text, ASCIIDOC, Creole, RDoc, textile and others.

That could be really nice. If GitHub would just display a package summary via godoc when README.md isn't present, I wouldn't have to keep generating them. But it also sounds far fetched/a lot of work to make it happen.

Didn't somebody once write a tool to auto-generate a README.md file from the Go program's source code?

I generate all of my Go package README.md files (and some other boilerplate, like .travis.yml) with gorepogen. See an example here. But it's pretty much customized exactly for my preferences. As I understand, people tend to make their own version of such a tool for their own needs.

@dolanor

This comment has been minimized.

Copy link

commented May 5, 2017

I was thinking about that lately.
It's true that the ideal would be that Github render the documentation from the source. Or at least link to godoc with the right URL. I don't know if it's so far fetched, it's just another format.
But for me go should be able to generate the godoc from the flags of a binary in the first place. (at least for the official "flag" package).

@dmitshur

This comment has been minimized.

Copy link
Member

commented May 5, 2017

But for me go should be able to generate the godoc from the flags of a binary in the first place. (at least for the official "flag" package).

Running with -help does list all flags that have been registered, along with their descriptions and default values, etc. This is automatic.

The only thing one needs to do in flag.Usage which is custom is to describe the command.

Perhaps someone can make a tool, which can be invoked via go generate, that parses godoc of a command and generates a corresponding flag.Usage implementation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
8 participants
You can’t perform that action at this time.