Fix the url in the titles and the files url + support examples generation

[aerostitch]

Closes: #2
Closes: #7
Currently in the title of the functions, methods, types, etc, even in thepackages list, the links are broken.
For example, you get titles like:

## <a name="ConfigSCM">type</a> [ConfigSCM](/src/target/configuration.go?s=4077:4383#L107)

What this PR does is that it uses the URLForSrc to rewrite the package name into a url using almost the same regex as the gddo project that handles godoc.org.
In the end the above title looks like:

## <a name="ConfigSCM">type</a> [ConfigSCM](https://github.com/beamly/go-gocd/tree/master/gocd/configuration.go?s=4077:4383#L107)

And a go package link that used to look like:

[resource_stages.go](/src/github.com/beamly/go-gocd/gocd/resource_stages.go)

Now looks like:

[resource_stages.go](https://github.com/beamly/go-gocd/tree/master/gocd/resource_stages.go)

Note that I only added the support for github and bitbucket but I think we can add later on the support for custom package url transformation regex patterns.

I guess it's also related to what was asked in #7 but I'm not 100% sure that what was meant by link generation is not implemented.
Anyway, let me know what you think about it. Happy to help on improving this.

Thanks
Joseph

[aerostitch]

Hi,

I just refactored my code to:

• add some unit tests
• support builtin packages
• support github.com. bitbucket.com (as it was in the 1st version)
• add a default support for all other websites (specific will be easy to add, just add your pattern here: https://github.com/davecheney/godoc2md/pull/20/files#diff-7ddfb3e035b42cd70649cc33393fe32cR60)

I also fixed an issue with the current template that adds an empty trailing space at the end of the list of package files.

Also, even with the -ex switch, the examples were not being processed (and we were trying to generate the html version anyway) so I took the example_textFunc from godoc, modified it to make it generate markdown and used it instead of example_html (note that if golang/tools#33 gets merged, we could use example_text2 directly to generate the examples).
An example can be seen in the examples/fs of this package. Another example can be seen in https://github.com/aerostitch/go-gocd-1/blob/add_examples/gocd/README.md#pkg-examples (or on upstream's https://github.com/beamly/go-gocd/blob/master/gocd/README.md if https://github.com/beamly/go-gocd/pull/116 has already been merged).

And lastly I updated the examples. You can have a look at what that generates here for example:
https://github.com/aerostitch/godoc2md/tree/links_issue/examples/build#index
https://github.com/aerostitch/godoc2md/tree/links_issue/examples/fs#index
https://github.com/aerostitch/godoc2md/tree/links_issue/examples/martini#index
https://github.com/aerostitch/godoc2md/tree/links_issue/examples/sessions#index

Let me know what you think.

Thanks
Joseph

[abursavich]

Thanks for doing this. I run some hacky sed commands to fix the URLs when I run godoc2md.

I ran into the problem of needing examples today and I didn't see that this PR existed, so I implemented it myself and opened #21. Now, I'm seeing this PR and I'm sorry about the collision.

FWIW, I initially implemented it very similarly to you, with an example_md function that spit out the markdown, but I realized that wouldn't work well if a user supplied an alternate template. My solution was to create an examples template function that outputs a slice of matching examples with formatted code and let the template decide how it's displayed.

type example struct {
	Name   string
	Doc    string
	Code   string
	Output string
}

func examplesFunc(info *godoc.PageInfo, name string) []*example { 
	//...
}

I defined a nested examples_md template inside the main template and used it where needed.

var pkgTemplate = `{{define "examples_md"}}{{range .}}
#### <a name="example_{{.Name}}">Example{{example_suffix .Name}}</a>
{{comment_md .Doc}}
Code:
{{pre .Code}}{{if .Output}}
Output:
{{output .Output}}
{{end}}
{{end}}{{end}}
...
{{range .Funcs}}{{$name_html := html .Name}}### <a name="{{$name_html}}">func</a> [{{$name_html}}]({{posLink_url $ .Decl}})
{{node $ .Decl | pre}}
{{comment_md .Doc}}
{{template "examples_md" (examples $ .Name)}}{{end}}
...
`

[aerostitch]

Hi @abursavich ,

I added the support for printing out the code output in the example_md function.
example_md would still spit out the markdown block so I'm not sure what will not work.
I added the example you were adding so that you can see the output: https://github.com/aerostitch/godoc2md/tree/links_issue/examples/errors#index

Anyway, this PR fixes several other issues (I needed a binary with all these fixes anyway), if @davecheney asks me to get rid of all the examples generation I'll do it, no biggy. (but given the other PR sitting here since November without comment I'm not sure he still got time for this project)
I think the 2 solutions are quite similar. It's just sad that you had to spend time doing something that was already done for the most part.

Joseph