x/tools/godoc: make codewalks more accessible to third parties

[Merovius]

It would be great if it was easier to write and distribute codewalks as documentation. The codewalk tool in godoc is pretty amazing. Writing a complete usecase of a library and a codewalk explaining it all would be an amazing way to complement testable examples and API documentation.

This could either happen by also loading codewalks from GOPATH-packages and showing them in godoc (and on godoc.org) or by factoring them into a separate tool which could then run hosted on appengine similar to go-talks.appspot.com.

[chewxy]

Bump on this.

I wrote a codewalk XML, before reading the how-to-write-codewalks part and realized that it only works for $GOROOT.

Felt like a gut punch.

[chewxy]

OK I'm irritated enough I'm willing to take a stab at this. How's this for a plan:

1. walk the $GOPATH and find codewalk.xml (each of has src which points within the $GOPATH
2. Display the listing in XXX/doc/codewalk/pkg
3. Populate things necessary in *Presentation such that the codewalk.html template can be populated

[Merovius]

I think it would be preferable to show them under pkg/ itself (say, github.com/user/repo/codewalk.html or something), as that would allow to show them on godoc.org too.

[as]

Does introducing a format other than XML fall under the scope of making the codewalks more accessible from an author perspective?

[chewxy]

I took a stab at it. It wasn't difficult.

Here's how it looks like:

Some considerations: the code right now scans for multiple codewalk_*.xml and codewalk.xml. I found that I can't get multiple codewalk.xml working due to codewalk.js relying on #codewalk-main. I'm too lazy to mess with JavaScript.

The endpoint is DOMAIN/codewalk/.... Before I proceed further with working on listing the codewalks, I think it might be a good idea to discuss this further.

Waiting comments from the Go team in particular

[adg]

Please send a CL.

Some considerations: the code right now scans for multiple codewalk_*.xml and codewalk.xml. I found that I can't get multiple codewalk.xml working due to codewalk.js relying on #codewalk-main. I'm too lazy to mess with JavaScript.

Can you expand on this? I don't understand the second sentence.

The endpoint is DOMAIN/codewalk/.... Before I proceed further with working on listing the codewalks, I think it might be a good idea to discuss this further.

It seems more natural to me that these should be

/doc/codewalk/package_path

where package_path is something like github.com/chewxy/repo/codewalk, where the file is github.com/chewxy/repo/codewalk.xml.

[adg]

Then they can be listed in /doc/codewalk/ as well.

[chewxy]

So the current codewalk.js works by finding #codewalk-main and then updating the elements.

I have this in the template (call this codewalk2.html):

{{ range $ := .Codewalks }}
{{/* the template here is copied from the current codewalk.html template */}}
{{end}}

If there is only one codewalk.xml it's fine. But if there are two (codewalk.xml and codewalk_2.xml), then the JavaScript bits start acting weird - only the first code walk will get interactivity. I inspected the JS but then I was too sleepy last night to work on it further.

Will send a CL when this is more complete.

[chewxy]

@adg Just to double check on the structure of the program, before I go ahead this weekend and implement it fully.

Should I implement/augment the codewalk handler in golang.org/x/tools/cmd/godoc or should I continue with my hack and implement it within the golang.org/x/tools/godoc.Presentation?

[adg]

@chewxy it's been a while since I looked at the code. Maybe just send out what you've got and I can help you iterate on the design from there?