godoc: maybe make the .md file visible

[robpike]

It's a shame that godoc (and godoc.org) do such a nice job showing package information
but don't present the .md file that is the github-traditional source of most
documentation. We should perhaps (I stress perhaps) do something about that.

Several possibilities arise:

1) Just publish the .md file in the output. Probably a bad choice since it would require
godoc to understand the format and figure out where to present it in the output. Godoc
already has enough to do.

2) Provide a separate tool that does understand .md file and writes a doc.go for you, so
it's easy to provide the information to godoc.

3) Provide a separate tool that takes godoc output and writes a .md file for you, so
it's easy to provide the information to github.

Probably more.

For discussion.

[minux]

Comment 1:

there are existing tools to do 3. e.g.
https://groups.google.com/forum/#!topic/golang-nuts/wGNwttzl19Y
I think converting doc to README.md for github is pretty
common among github projects, so we don't need to do 1 as the
converted markdown docs will be duplication anyway.
It feels like option 2 reverses the information flow, as we
should recommend idiomatic and accurate docs in Go source code
instead of writing docs in markdown files first and then importing
into Go source.

[bradfitz]

Comment 2:

4) fix github

[cznic]

Comment 3:

I prefer to keep the two things unrelated by any automatic means. I use READMEs that are
basically just a link to the relevant godoc.org page.

[rsc]

I'd like to see a godoc html output -> md file generator in some form.
(Probably directly, not by parsing the html.)

[arvenil]

Still missing this. This or at least properly working #2381
Right now it's really difficult to produce nice documents for internal/private tools.

[kegsay]

I might take a stab at this (option 3) - are there any available docs on the structure of the plaintext output of godoc so I don't need to do this by trial and error as I encounter new sections? Also, as per #2381 (comment), how should dependencies be linked together?

EDIT: Scratch that, looks like I've been beaten

[dsnet]

Is this issue still relevant given that https://pkg.go.dev shows the readme.md file for modules?

[seankhliao]

pkgsiste does this.