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

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

Open
Merovius opened this issue Feb 17, 2016 · 11 comments

Comments

@Merovius
Copy link

commented Feb 17, 2016

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.

@adg adg self-assigned this Feb 18, 2016

@adg adg changed the title Make codewalks more accessible to third parties x/tools/godoc: make codewalks more accessible to third parties Feb 18, 2016

@bradfitz bradfitz added this to the Unplanned milestone Apr 10, 2016

@adg adg removed their assignment Feb 14, 2018

@adg adg added the help wanted label Feb 14, 2018

@chewxy

This comment has been minimized.

Copy link

commented May 12, 2018

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

This comment has been minimized.

Copy link

commented May 12, 2018

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

This comment has been minimized.

Copy link
Author

commented May 13, 2018

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

This comment has been minimized.

Copy link
Contributor

commented May 13, 2018

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

@chewxy

This comment has been minimized.

Copy link

commented May 14, 2018

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

Here's how it looks like:

image

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

This comment has been minimized.

Copy link
Contributor

commented May 14, 2018

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

This comment has been minimized.

Copy link
Contributor

commented May 14, 2018

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

@chewxy

This comment has been minimized.

Copy link

commented May 14, 2018

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

This comment has been minimized.

Copy link

commented May 18, 2018

@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

This comment has been minimized.

Copy link
Contributor

commented May 21, 2018

@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?

@chewxy

This comment has been minimized.

Copy link

commented May 22, 2018

yep ok. I've not actually started on it. Will do soon

@gopherbot gopherbot added the Tools label Sep 12, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.