P5.js: Offline Documentation

[ducklin5]

I'm sorry to have to bring up another one of these but the others I have seen just haven't answered the question, just keeps making me jump around GitHub. Is there an offline documentation (like an offline version of the site). I would just like the reference though not the whole site, as that seems to be pretty large.

[joecridge]

Since this has come up again (and because a lot of p5.js users are OS X users too), what would be really awesome is if we could arrange for the p5.js docs to be included with Dash.

I don’t know how much effort would be involved in making that happen, but I think it would be indispensable!

[futuremarc]

That's a great idea to publish to Dash! I'll make this happen since I was trying to build an offline mode anyway

[dhowe]

Is this preferable to generating a set of docs on build to be included with downloads ? Or are you thinking to have both?

[ducklin5]

I ended up using the original processing docs on zeal

[futuremarc]

@dhowe ultimately both

[alelepd]

I also think having offline docs would be nicer. So far Im using a .pdf reference from Processing because I noticed they are very similar.

My country suffers from a very drastic electricity problem (Venezuela); when the lights go out, the internet does too, so its very important to have offline resources to continue working and learning until the electricity is restored.

Edit: Oh boy, I am just discovering Dash. Very useful indeed.

[BlandSauce]

The online reference seems to mostly work offline.
I downloaded everything from https://github.com/processing/p5.js-website/tree/main/
After also downloading jquery and changing the reference to it in /reference/index.html, it works offline almost 100%. The problem is that clicking links normally (or from search) only add the appropriate #anchor to the url bar. Opening in new tab instead works just fine. There's also some formatting issues with the code examples. I haven't dug around too much to see what all is actually needed, but it seems like an offline version could be figured out, then updated just by replacing the data.json already being generated for the online version.

[limzykenneth]

@BlandSauce I've made a proof of concept actually: https://github.com/limzykenneth/p5.js-reference

For this I'm just wondering what kind of format would best fit it: a offline website, a packaged app, a pdf or something else?

I'm a bit preoccupied at the moment but if anyone is interested, you can have a look at that repo. Cheers.

[dhowe]

From my perspective, an offline website (same as the online reference) would be ideal

[limzykenneth]

The problem with an offline website is that simply double clicking index.html would not work since features like videos etc would need to be run on a server, and I feel it's too much to expect someone to run a server to read the docs...

[dhowe]

Which videos are you referring to? The only problem I see loading index.html from your repo is that its using an AJAX request to fetch the json data... otherwise most things work OK

[limzykenneth]

@dhowe Sorry, I meant capture such as this but apparently the example was not enabled the maybe it won't be a problem after all. The ajax call to data.json can be changed rather easily I think so maybe this is possible. 😃

[lmccart]

This is great, so so useful and important. I think offline website makes sense, even if a few server-requiring features don't work. We could package it with the p5.js complete download.

[ducklin5]

Putting it in the complete package would be great so long as its not too heft. Otherwise as a separate download. Wouldn't want to force users to download something they don't want

[lamarqua]

Please make it available offline.

[limzykenneth]

Good news! The prove of concept is fully working. Have a look here, it will work by simply double clicking on index.html at the root of the folder. I figure that will be easiest and not confuse any beginner with all the files they don't need to look at.

Essentially, it is just a strip down version of the full reference site at p5js.org/reference. The main changes that will differ between generating the reference for the actual site and this offline reference ishe variable name at the beginning, probably can be automated on build) from data.json and update that instead. Now the question is should this offline documentation be maintained as a separate project, pulling in changes other than data.json changes manually or should it be merge into the main p5.js project and create a build step to build it from the current reference files. The second option is a bit more work now and may include rewriting the way the reference is generated, not sure, but it sure does save time in the future and prevent errors. The code now could be a bit messy as well because I don't want to change too many things pending the decision on how to build this.

Kinda long update, let me know what everyone thinks! @lmccart @dhowe @futuremarc

[ducklin5]

I vote for the first option, a separate repo would be alot better to keep the p5.js repo slim

[lmccart]

I wonder if it is possible to host in a separate repo (to keep p5.js repo smaller), but to set up a github webhook and process that would automatically update somehow? this is just an idea... I haven't though too far into how complicated that would be code-wise.

[lmccart]

btw fantastic work on this! this is such crucial work, thank you!

[limzykenneth]

I like the idea of a webhook doing the update automatically. I'm not that familiar with github webhooks but I did find this on stackoverflow. There might be other ways but I can't think of any at the moment.

[lmccart]

yeah, something like that was what I was thinking. I can take a look at this part if you like, if you want to just set up a repo with the files and stuff to generate the docs?

[limzykenneth]

@lmccart That'll be great, I'll spend some time finalising the structure of the repo then.

[limzykenneth]

Pushed an update. Tried out many different ways to build, including building from source and some clever handlebars + cp action but I think the easiest is really to do what we are already doing for p5.js-website, copy the whole reference folder.

To setup a webhook, it can run the build on p5.js repo and generate the reference folder, push it to the offline docs repo's dist folder. On the offline docs side, another hook can be setup so that it runs its build on push generating data.js from data.json. To change the layout and design of the offline docs, relevant files are in dist/offline-docs.

To publish, simply package the contents of the dist folder and a user can simply just double click index.html. I'm still working to make it responsive.

[lmccart]

cool! I'll take a look at getting this all hooked up this week.

[lmccart]

hi @limzykenneth I took a look through your repo and looked into pushing things around between repos. the tricky thing about this is that we have to be running a node server, I couldn't find a good way around this. so I decided the easiest thing was just to add this into the p5.js-website repo and let it build from there whenever the reference/ folder is updated. I basically just ported your gulp task to php, and copied a few of the files you modified.

if you hit this url: http://p5js.org/offline-reference/build-ref.php, it will rebuild the latest ref into p5-reference.zip, which can be found here: http://p5js.org/offline-reference/p5-reference.zip. you can check out the code here: https://github.com/processing/p5.js-website/tree/main/offline-reference.

I think I captured all your custom modifications in the port and copy but let me know if anything looks wrong or I missed any. if we're all good, I can set up a webhook that will ping that url to rebuild on reference change, and then we can add a zip download link to the online reference page and download pages somewhere.

thanks for all your work on this!

[limzykenneth]

@lmccart I think some styling rules are missing, probably from render.js, they are used to accommodate browsing on mobile. Come to think of it, they might not be that important since there isn't really a way to read the docs on mobile at the moment. Anyway, this is what it looks like now:

and this is what I have on my repo:

Other than that, everything looks great! Pretty excited to get it out there.

[lmccart]

good catch @limzykenneth on the mobile formatting, I just added that styling in from render.js.

ok I think we're good! link added to the reference page and it will be included in future p5.js complete build zips as well. thanks everyone for your input and work on this! yaaay