Link doc entries to their definition in p5 source code. #1248

Merged
merged 1 commit into from Feb 11, 2016

Conversation

Projects
None yet
4 participants
@toolness
Member

toolness commented Feb 11, 2016

One of the hardest things about fixing a minor bug or typo is figuring out where it's located in a project's source code.

But one of the great things about YUIDoc is that it gives us that information in the data.json blob it builds for our reference docs!

So I thought that it might be nice to unintrusively link to the source code for a p5 API in its documentation. I stress the word unintrusively because I don't want to confuse the beginners who may be learning programming for the first time, and could be thrown off by the extra information.

Other benefits of linking to the source:

  • It invites users of p5 to become contributors.
  • It generally makes it easier to "pop open the hood" and see how p5 works.

Here's what it looks like--the example screenshot below is taken from the documentation for plane():

2016-02-11_8-58-28

The first link there is to view the source for plane(), while the second is to edit it (yay to GitHub for providing permalinks to edit files at a specific line number!). My hope is that beginners who don't know anything about git can fix simple typos and issue PRs for them.

Notes:

  • Um, I couldn't easily figure out where the CSS for the docs were stored, so I've inlined the CSS for now. It is kind of gross but I should be able to fix it before merging.
@iamjessklein

This comment has been minimized.

Show comment
Hide comment
@iamjessklein

iamjessklein Feb 11, 2016

Contributor

👍 I agree this feels like a super humane approach to redirects @toolness

Contributor

iamjessklein commented Feb 11, 2016

👍 I agree this feels like a super humane approach to redirects @toolness

@PaliwalSparsh

This comment has been minimized.

Show comment
Hide comment
@PaliwalSparsh

PaliwalSparsh Feb 11, 2016

Contributor

This is simply amazing. 😃

Contributor

PaliwalSparsh commented Feb 11, 2016

This is simply amazing. 😃

@lmccart

This comment has been minimized.

Show comment
Hide comment
@lmccart

lmccart Feb 11, 2016

Member

brilliant, love it. we also have this addition to the footer. i'm going to go ahead and merge both and then you or i can take a crack on styling. the css files are actually located in the p5.js-website repo: https://github.com/processing/p5.js-website/blob/master/css/main.css

Member

lmccart commented Feb 11, 2016

brilliant, love it. we also have this addition to the footer. i'm going to go ahead and merge both and then you or i can take a crack on styling. the css files are actually located in the p5.js-website repo: https://github.com/processing/p5.js-website/blob/master/css/main.css

lmccart pushed a commit that referenced this pull request Feb 11, 2016

Lauren McCarthy
Merge pull request #1248 from toolness/link-docs-to-source
Link doc entries to their definition in p5 source code.

@lmccart lmccart merged commit 3c58b8b into processing:master Feb 11, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment