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):
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!
.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.
.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 for USES/APPEND_USES are:
// Boards Espruino Board EspruinoWiFi Pico Puck.js Pixl.js 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
Step 1: Obtain Espruino Source Code & Web Tools
Check out the
EspruinoWebTools repositories at the same same level as
EspruinoDocs folder. Assuming you're in the
$ cd .. $ git clone firstname.lastname@example.org:espruino/Espruino.git` $ git clone email@example.com:espruino/EspruinoWebTools.git $ cd EspruinoDocs
Step 2: Install Node.js® and npm
If you have Node.js and npm installed skip this step.
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
nodejs at the terminal.
Step 3: Install Required Node Modules
$ npm install
The bash script does 3 things:
- Uses the
Espruinosource code to generate the pinout diagrams.
- Builds the production site at
You will have to run
build.sh at least once if you want the
build.js to work.
To Do a Full Build
To Build Documentation Only
Note: You've had to have least ran the bash script once for this to build successfully.
$ npm run build
The output will be placed in the
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
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
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