usability: Need to add documentation for a binary in three different places #20212
Comments
|
Didn't somebody once write a tool to auto-generate a README.md file from the Go program's source code? |
|
I forget. That might've been the one I saw. I've never used one. |
|
For going the other way there is: sectioneight/md-to-godoc |
You'd need to do this in a safe execution environment, since you're executing arbitrary binaries (any user code can be inside
That could be really nice. If GitHub would just display a package summary via
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. |
|
I was thinking about that lately. |
Running with The only thing one needs to do in Perhaps someone can make a tool, which can be invoked via |
ianlancetaylor
added
the
NeedsInvestigation
If I'm shipping a Go binary, generally, I need to add documentation in three different places:
a README or README.md file, for people visiting the project via Github. This contains usage information and usually also installation information
in
doc.goor similar, so it appears via godoc. Some go tools document this well, but many tools fall down on the docs here:in
flag.Usage, so it looks nice when printed at the command line, and shows you the various arguments you can run.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
mainfunction has no package docs, but modifiesflag.CommandLine, godoc could callflag.PrintDefaults, or call the binary with-hand 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
mainfunction has no package docs but has a README.md,godoccould 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.
The text was updated successfully, but these errors were encountered: