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

godoc: maybe make the .md file visible #8198

Open
robpike opened this issue Jun 12, 2014 · 6 comments

Comments

@robpike
Copy link
Contributor

commented Jun 12, 2014

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

This comment has been minimized.

Copy link
Member

commented Jun 12, 2014

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

This comment has been minimized.

Copy link
Member

commented Jun 12, 2014

Comment 2:

4) fix github
@cznic

This comment has been minimized.

Copy link
Contributor

commented Jun 13, 2014

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

This comment has been minimized.

Copy link
Contributor

commented Apr 10, 2015

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

@rsc rsc added this to the Go1.5Maybe milestone Apr 10, 2015

@rsc rsc modified the milestones: Unplanned, Go1.5Maybe Jul 15, 2015

@arvenil

This comment has been minimized.

Copy link

commented Jan 29, 2016

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

This comment has been minimized.

Copy link

commented Nov 2, 2016

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

@ALTree ALTree added NeedsDecision and removed Thinking labels Aug 10, 2017

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.