Espruino by Examples

Hi, just found this really nice set of Espruino examples (I'm not an author of that project):
https://github.com/anars/Espruino

That resource would be much better if it conformed to the style guide (and practices) of Espruino. Even better still, if they were contributed to the official documentation. I guess a collection of examples / cookbook is something that could fit well somewhere here https://github.com/espruino/EspruinoDocs­

Woah. That's a lot of examples. Someone's done a good deal of work on that. I wonder who?!

Is there any place on Espruino server, which points to sources like this ?

Whoa - that's a lot of stuff!

I did a quick google of my inbox, and Kay Anar (who wrote these) has actually been looking at Espruino with Tom Igoe (one of the Arduino founders). I guess this is the result of his efforts - but I had absolutely no idea!

I agree though, it'd be nice if he used the more 'normal' K&R coding style. As it is you can't paste the code into the left-hand side of Espruino, because the first line of a function declaration doesn't contain an open bracket - so is treated as a complete statement.

I don't really have anywhere for this, no. I have http://www.espruino.com/Links but it's pretty out of date now.

Any thoughts about what could link to this? I think it'd be good to add something - not just for this, but for other tutorials and videos that have been posted up on other servers.

As I see it you have two questions:

1. How should you handle external resources (videos, links, repositories etc)?
   
2. Would you concider splitting /Tutorials into
   
   1. Tutorials (step by step guides)
      
   2. Examples (example usages and solutions to recurring problems/tasks, such as setTimout|Interval|Watch
      
   3. Projects (complete user contributed projects)
      
      

(I always get too engaged in these kinds of things so please feel free to ignore everything I say here...)

I imagine that a way to do it would be to define the following kinds of external resource:

1. (github) Project (a complete and tested project, maybe with README.md, project.js and parts.txt which describes the parts needed to complete the project)
   
2. (github) Example (README.md <- entire example in one file with images in repo or in /img)
   
3. (github) Tutorial (README.md as the introduction laying out the intent etc, then append part1.md, part2.md ... partX.md before building the resulting HTML)
   
4. (vimeo, youtube, ???) video resource
   
   

Then, you could have some JSON files in your EspruinoDocs i.e examples.json, projects.json and tutorials.json. Contributors could then make a PR with an addition to one of those files ("add ESP8266 as Access Point tutorial"). If you accepted, we could extend the EspruinoDocs build to pull in the various resources, compile HTML and link in to them as an espruino.com page (probably a good idea to link to the github issues for reporting problems, then maintenance is on the contributor).

I could also write up a small script to 'format' anars' samples if he would accept it.

That's my all-to-many bytes on the matter. What are your thoughts @Gordon?

Hmm, I'm not too sure about the extra split... We already have Tutorials and Examples, and if I'm honest even that is a little confusing. I'm not sure what others think?

Definitely having the ability to link to other pages (especially if on GitHub) would be great... I think hosting them would be a bad idea, but definitely to include links on the site and add keywords for the search function would be great.

After thinking on it some more I completely agree. I come from the Wiring/Arduino pattern of thought where the target audience is not a developer but a non-cs creator. In that context, linking to github archives directly can be scary but that does of course not apply for Espruino (FWIW; I did not really propose to host the repo, just the compiled .html from the .md file).

I think linking to GitHub wouldn't be too scary for people - after all, it's just one more site, not a mix of sites that all look different.

Most of the examples in EspruinoDocs are actually parsed out of a single JS file with comments in the top. Doing that for code on GitHub too would be pretty cool, but I'm still a little worried about putting totally uncurated code on the Espruino site.