godoc should have a -markdown flag for github README.md

[bradfitz]

Github README files can be in a dozen formats:

https://github.com/github/markup#readme

But you'll note that HTML isn't one of them.
And text files aren't pretty.

Godoc should make it easy to generate README.md (markdown) files for github README pages.

People are struggling to do it by hand: https://github.com/ziutek/mymysql ... including
myself.  It takes a bunch of fixing.

We could make this easier.

[rsc]

Comment 1:

godoc already has -templates.

[bradfitz]

Comment 2:

Cool, that should make it easier.
We're pushing goinstall and code hosting sites.  We need to make it even easier.  I'm
spending more time today fighting godoc & goinstall & directory layouts than I am
writing code.

[bradfitz]

Comment 3:

Not sure how I'm supposed to use them, though.
$ godoc godoc | grep template | wc -l
0
$ godoc
...
  -templates="": directory containing alternate template files
...

[rsc]

Comment 4:

I know, but I don't want godoc to be a kitchen sink for flags.
I think it's fine to have lib/godoc/markdown (or lib/godoc/github)
but I think it's not hard to say
godoc -templates $GOROOT/lib/godoc/markdown
to use it.

[rsc]

Comment 5:

i think if you say -templates then it looks there
before looking in lib/godoc for template files.
so you'd start with a copy of the lib/godoc files
and customize.

[bradfitz]

Comment 6:

Yeah, I'm getting it working.  I need to add a formatter to mess with whitespace,
though.  Markdown is picky.
What I got so far: https://github.com/bradfitz/gomemcache/blob/master/godoc.md

[bradfitz]

Comment 7:

Giving up, since the template package is being redone anyway and I would've had to add
formatters to get it 100% nice.
Plus I found Gary Burd's awesome service on App Engine:
     http://gopkgdoc.appspot.com/pkg/github.com/bradfitz/gomemcache
Instant docs.

Status changed to Retracted.