• Stars
    star
    254
  • Rank 160,264 (Top 4 %)
  • Language
    JavaScript
  • License
    Other
  • Created about 11 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

See http://espruino.com for the complete Espruino Documentation - many links in this repository will not work

Espruino Documentation and Code


PLEASE VIEW THIS DOCUMENTATION ON WWW.ESPRUINO.COM - you can even Search. The markdown files in this repository are designed to be parsed by a build script - by viewing them on GitHub you may be missing useful links or information.


This project generates the website and tutorial code for Espruino.com. This also contains the modules that can be required by the Espruino Web IDE. You can contribute to the site and modules in this project.


Documentation files are written GitHub Markdown with additional metadata. Basically, a script that looks for the following (on the start of a line):

* KEYWORDS: Comma,Separated,List ; Defines keywords for this file
* APPEND_KEYWORD: Keyword        ; Append a list of pages that match the keyword
* USES: Comma,Separated,List  ; Defines parts that are used by the given tutorial
* APPEND_USES: part              ; Append a list of pages that have this part in their USES_PARTS list
* APPEND_JSDOC: filename         ; Append JavaScript documentation based on the JS in the given file
* APPEND_PINOUT: boardname       ; Append Pinout for the given board
* BUYFROM: normalprice,bulkprice,link1,link2|optional_name,link3  ; Append a floating 'buy from' window
* APPEND_TOC                     ; Append a table of contents made from H1/H2/H3 (and add them as keywords)
* LIST_LINKS_AS_KEYWORDS         ; Add lists of links `* [...](...)` as keywords

It also looks for a title (second line, after copyright notices) which it uses to create the title of the HTML page (and of links to it).

There are a few extra bits too:

  • [[My Page]] links to a page on the Espruino website
  • [[http://youtu.be/VIDEOID]] puts a video on the page
  • ![Image Title](MyFilename/foo.png) Adds an image. Images should be in a directory named after the filename of the file referencing them (or the same directory as the file referencing them)
  • The first image in the file (or a file named PageName.thumb.jpg/png) is resized and used as the thumbnail. If there's no image on the page at all it's added top-right.

It then converts the Markdown to HTML and shoves it on the Espruino website. Lovely!

JavaScript

Any .js files in examples have a webpage created that uses the comments as markdown, and then adds the code as a code block right at the end.

All other .js files are treated as modules. They are minified using Google's online closure compiler and the SIMPLE_OPTIMISATIONS flag. To get advanced optimisations, you must add the exact text @compilation_level ADVANCED_OPTIMIZATIONS into the comments at the head of the file.

Common keywords

Common keywords for USES/APPEND_USES are:

// Boards
Espruino Board
EspruinoWiFi
Pico
Puck.js
Pixl.js
Bangle.js
Bangle.js2
MDBT42Q
MicroBit
Thingy52

// Other things
Internet       An internet connection
Graphics       Graphics Library
Waveform       Waveform Library
AT             AT Command library
Speaker
PWM
Infrared
ESP8266        ESP8266 attached to an Espruino
BLE            Bluetooth LE (eg via Puck.js) but may need board-specific hardware
Only BLE       Bluetooth LE (eg via Puck.js) but applicable to anything
Web Bluetooth

Common keywords for KEYWORDS/APPEND_KEYWORDS are:

Espruino
Official Board
PCB
Pinout                 Page contains pinout info

Build Requirements

Step 1: Obtain Espruino Source Code & Web Tools

Check out the Espruino and EspruinoWebTools repositories at the same same level as EspruinoDocs folder. Assuming you're in the EspruinoDocs folder...

$ cd ..
$ git clone [email protected]:espruino/Espruino.git`
$ git clone [email protected]:espruino/EspruinoWebTools.git
$ cd EspruinoDocs

Step 2: Install Node.js® and npm

If you have Node.js and npm installed skip this step.

If you haven't got Node.js JavaScript runtime installed or the JavaScript Package managers installed do so via the installation guides below.

On Linux, you may have nodejs and not node in your path. This will lead to issues later on in the build process. This problem is easily solved by running sudo ln -s /usr/bin/nodejs /usr/bin/node which will create a symbolic link, so you can use both node and nodejs at the terminal.

Step 3: Install Required Node Modules

In order to generate the documentation and view it you require several JavaScript packages. To install them issue the following command:

$ npm install

This will install all JavaScript dependencies.

Build Process

Currently they are two build scripts. One bash, one JavaScript.

The bash script does 3 things:

  1. Uses the Espruino source code to generate the pinout diagrams. python is required
  2. Builds the production site at ~/workspace/espruinowebsite
  3. Builds Espruino specific modules and minifies the JavaScript code

The JavaScript build process just builds the documentation in the html folder.

You will have to run build.sh at least once if you want the build.js to work.

To Do a Full Build

Run:

$ ./build.sh

To Build Documentation Only

Note: You've had to have least ran the bash script once for this to build successfully.

Run:

$ npm run build

The output will be placed in the html directory.

View Generated Documentation

You can load a development version of the website locally. It will not look exactly like the production site but you can test your build and links.

$ npm start

Then load up a page in a browser: http://localhost:3040/Original

Troubleshooting

OS X

Set Maximum Open Files

On OSX, most likely the default amount of open files will be set too low. This may cause an error during the build, like: "Error: EMFILE, too many open files 'tasks/File Converter.md'"

Make sure you have at least 1024 for the value of open files.

$ ulimit -n       # see current limit

Increase the limit:

$ ulimit -n 1024  # increase to 1024

Linting

You can lint modules using:

# Install required tools
npm install eslint

# Lint all js files in devices folder
npm run eslintdevices

# Lint all js files in modules folder
npm run eslintmodules

# Lint all js files in boards folder
npm run eslintboards

More Repositories

1

Espruino

The Espruino JavaScript interpreter - Official Repo
C
2,749
star
2

BangleApps

Bangle.js App Loader (and Apps)
JavaScript
490
star
3

EspruinoWebIDE

The Espruino Web IDE - A Chrome Web App for programming Espruino
JavaScript
364
star
4

EspruinoHub

A BLE -> MQTT bridge for Raspberry Pi and other Embedded devices
JavaScript
233
star
5

EspruinoBoard

Espruino and Puck.js Board Schematics
OpenSCAD
163
star
6

EspruinoTools

JavaScript library of tools for Espruino - used for the Web IDE, CLI, etc.
JavaScript
148
star
7

EspruinoBuilds

Espruino Binaries for in-development platforms
50
star
8

EspruinoOrion

Plugin for Eclipse Orion + Espruino
JavaScript
47
star
9

TinyDash

A Tiny IoT Dashboard, small enough to serve from embedded devices
JavaScript
28
star
10

espruino-tools

Node module to allow command-line access to Espruino
26
star
11

making-things-smart

Code examples for the Making Things Smart book
JavaScript
26
star
12

EspruinoWebTools

Tools/utilities for accessing Espruino devices from websites
JavaScript
22
star
13

webaudio-oscilloscope

A simple, auto-triggering Oscilloscope that uses the Web Audio API and your Mic input
JavaScript
21
star
14

EspruinoAppLoaderCore

Core code used for Bangle.js and Espruino app loaders
JavaScript
9
star
15

EspruinoApps

App loader for installing applications on Espruino devices
JavaScript
8
star
16

EspruinoBuildTools

Build tools needed to build Espruino on embedded platforms
Shell
8
star
17

EspruinoHost

Multiplatform WebSocket server that provides USB Serial and Bluetooth LE capabilities to Espruino IDE
C++
7
star
18

winnus

Windows 8.1 and above BLE NUS support for Node.js
C++
3
star
19

EspruinoMemView

Display the contents of an Espruino device's RAM as a Network
HTML
3
star
20

EspruinoDemos

Source code for Espruino demos used at exhibitions
JavaScript
2
star
21

AndroidBLEAdvertiser

App to fetch a webpage in the background, parse data, and set your phone's Bluetooth advertising
Java
2
star
22

EspruinoTester

Raspberry Pi based test harness for testing Espruino on boards (in development)
Tcl
2
star
23

espruino.github.io

Espruino Main Website
JavaScript
1
star