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

proposal: add illustrations to documentation pages #39513

Open
ajstarks opened this issue Jun 10, 2020 · 16 comments
Open

proposal: add illustrations to documentation pages #39513

ajstarks opened this issue Jun 10, 2020 · 16 comments

Comments

@ajstarks
Copy link
Contributor

@ajstarks ajstarks commented Jun 10, 2020

What is the URL of the page with the issue?

Any API documentation URL (for example: https://pkg.go.dev/gioui.org/layout?tab=doc)

What is your user agent?

Mozilla/5.0 (X11; Fedora; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.97 Safari/537.36

What did you expect to see?

I would like to support adding illustrations to documentation pages. Perhaps one method would be to show an image triggered by a magic comment:

// Foo does ....
//  ![foo illustration](link-to-image.png)
func Foo(....) 
 



@gopherbot gopherbot added the pkgsite label Jun 10, 2020
@gopherbot gopherbot added this to the Unreleased milestone Jun 10, 2020
@dmitshur
Copy link
Member

@dmitshur dmitshur commented Jun 11, 2020

Also see #16666.

@julieqiu julieqiu changed the title go.dev: Feature request: add illustrations to documentation pages go.dev: add illustrations to documentation pages Jun 12, 2020
@julieqiu julieqiu changed the title go.dev: add illustrations to documentation pages x/pkgsite: add illustrations to documentation pages Jun 15, 2020
@myitcv
Copy link
Member

@myitcv myitcv commented Sep 22, 2020

I would like to support adding illustrations to documentation pages. Perhaps one method would be to show an image triggered by a magic comment:

// Foo does ....
//  ![foo illustration](link-to-image.png)
func Foo(....) 
 

A possible refinement of this suggestion would be to leverage the fact that directives are not included as part of go doc documentation:

package x

// Foo does ....
//godoc:image ![foo illustration](link-to-image.png)
func Foo() {}

and:

$ go doc Foo
package x // import "."

func Foo()
    Foo does ....

@ajstarks
Copy link
Contributor Author

@ajstarks ajstarks commented Sep 22, 2020

@julieqiu can you suggest some next steps? (Possibly discussing at the next tools call)

@ajstarks
Copy link
Contributor Author

@ajstarks ajstarks commented Sep 22, 2020

Here is a mockup of what it would like:

// Circle makes a filled circle, using percentage-based measures
// center is (x,y), radius r
//godoc:image ![illustration of circle](circle.png)
...

// Ellipse makes a filled circle, using percentage-based measures
// center is (x,y), radii (w, h)
//godoc:image ![illustration of ellipse](ellipse.png)

Screenshot from 2020-09-22 13-10-00

@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Sep 23, 2020

Thanks, @ajstarks! I like this suggestion.

@jayconrod @bcmills for thoughts on using directives for this.

@bcmills
Copy link
Member

@bcmills bcmills commented Sep 23, 2020

The Go project has historically resisted adding much in the way of structured formatting to doc comments (#35947 (comment))

Personally I don't have a strong opinion on the matter either way, but given the history I would be inclined to send this through the proposal process.

See also #25444, #16666, #7873, #25449, #18342 (comment).

@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Sep 24, 2020

@ajstarks - filing a proposal for this issue would be a good next step. See https://github.com/golang/proposal for details.

@ajstarks
Copy link
Contributor Author

@ajstarks ajstarks commented Sep 24, 2020

thanks @julieqiu . Do I need to make a new proposal issue? Should the Proposal tag be added to this issue? Is a design doc required at this stage?

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Sep 24, 2020

I think to start it would be sufficient to turn this issue into a proposal by adding the Proposal label, as described in step 1 of https://github.com/golang/proposal#the-proposal-process. That can be done by adding a "proposal:" prefix to the issue title. You may be asked for a design doc as part of step 2.

@ajstarks ajstarks changed the title x/pkgsite: add illustrations to documentation pages Proposal: x/pkgsite: add illustrations to documentation pages Sep 24, 2020
@julieqiu julieqiu changed the title Proposal: x/pkgsite: add illustrations to documentation pages proposal: x/pkgsite: add illustrations to documentation pages Sep 24, 2020
@julieqiu julieqiu added the Proposal label Sep 24, 2020
@julieqiu julieqiu changed the title proposal: x/pkgsite: add illustrations to documentation pages proposal: add illustrations to documentation pages Sep 24, 2020
@dmitshur dmitshur modified the milestones: Unreleased, Proposal Sep 24, 2020
@ajstarks
Copy link
Contributor Author

@ajstarks ajstarks commented Oct 1, 2020

FYI: here is the proposal in more detail:
https://github.com/ajstarks/go-illustration/blob/master/proposal.md

@bcmills
Copy link
Member

@bcmills bcmills commented Oct 1, 2020

I note that the proposal suggests that go doc should not render the alt-text for the image.

I think that would put terminal readers at a significant disadvantage vs. the alternative today (explicit URLs), since they wouldn't even know that there was other content available in the documentation. (We probably need to figure out some way to indicate the elided content on the terminal, if not display the content URL.)

@ajstarks
Copy link
Contributor Author

@ajstarks ajstarks commented Oct 1, 2020

Perhaps I should be more explicit on alt-text handing. The intention is that agents are free to use the alt-text as they see fit. I also could update the recommendations to include "good" alt-text, assuming that it will be rendered.

@ianlancetaylor ianlancetaylor added this to Incoming in Proposals Oct 1, 2020
@yiyus
Copy link

@yiyus yiyus commented Oct 2, 2020

I do not have a strong opinion about this, but I think it would be preferable if the magic comment did not look like one. For example, the magic comment may be: "See figure circle.png (ilustration of a circle)".

@ajstarks
Copy link
Contributor Author

@ajstarks ajstarks commented Oct 4, 2020

@yiyus I like the notion of a more natural language approach very much. Do you have an opinion on the relative difficulty of implementation vs. the // godoc:image method?

@bcmills
Copy link
Member

@bcmills bcmills commented Oct 21, 2020

@yiyus, @heschik points out that a convention like “See figure ().” might be challenging for authors of non-English documentation.

We have a similar precedent in the // Deprecated: comments for APIs and // Output: comments for Example functions, so perhaps the format here could be something like // Image: <file> (<alt-text>).

@sbinet
Copy link
Member

@sbinet sbinet commented Jan 8, 2021

if we go w/ the // Image: <file> directive, could we also devise a way to integrate it somehow with func ExampleXYZ() ?

it would be quite useful and convenient for packages dealing with graphics, not only to be able to document APIs with pictures, but to also document their examples with those.

I guess I am not proposing // Image: to be a reference output for the example (as the image may slightly vary from platform to platform, and it's not as easy than for, say, floating point data to "ignore" noise).
but being able to document the ExampleXYZ function with // Image: and have that image being displayed with the example would go a long way.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Proposals
Incoming
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
8 participants