Tutorial website

test_all.js

@@ -4,7 +4,7 @@ const { execSync } = require('child_process')
 const chalk = require('chalk')
 const semver = require('semver')
 
-const excludeFolder = ['node_modules']
+const excludeFolder = ['node_modules', 'website']
 
 function getAllTests() {
   return fs

website/.editorconfig

@@ -0,0 +1,18 @@
+# editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.rb]
+indent_style = space
+indent_size = 4

website/.gitattributes

@@ -0,0 +1,65 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# These files are text and should be normalized
+*.bat text eol=crlf
+*.coffee text
+*.css text
+*.htm text
+*.html text
+*.inc text
+*.ini text
+*.js text
+*.json text
+*.jsx text
+*.less text
+*.sass text
+*.scss text
+*.sh text eol=lf
+*.sql text
+*.ts text
+*.tsx text
+*.xml text
+*.xhtml text
+
+# These files are binary and should be left untouched
+# (binary is a macro for -text -diff)
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.mov binary
+*.mp4 binary
+*.mp3 binary
+*.flv binary
+*.fla binary
+*.swf binary
+*.gz binary
+*.zip binary
+*.7z binary
+*.ttf binary
+*.eot binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+
+# Custom for Visual Studio
+*.cs     diff=csharp
+*.sln    merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+# Standard to msysgit
+*.doc    diff=astextplain
+*.DOC    diff=astextplain
+*.docx diff=astextplain
+*.DOCX diff=astextplain
+*.dot  diff=astextplain
+*.DOT  diff=astextplain
+*.pdf  diff=astextplain
+*.PDF    diff=astextplain
+*.rtf    diff=astextplain
+*.RTF    diff=astextplain

website/.gitignore

@@ -0,0 +1,119 @@
+# =========================
+# Node.js-Specific Ignores
+# =========================
+
+# Build directory
+public/
+
+# Gatsby cache
+.cache/
+
+# npm lockfile
+# since we use yarn, this can be ignored
+/package-lock.json
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Typescript v1 declaration files
+typings/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# =========================
+# Operating System Files
+# =========================
+
+# OSX
+# =========================
+
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Thumbnails
+._*
+
+# Files that might appear on external disk
+.Spotlight-V100
+.Trashes
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Windows
+# =========================
+
+# Windows image file caches
+Thumbs.db
+ehthumbs.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk

website/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Kata.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

website/README.md

@@ -0,0 +1,71 @@
+# The N-API Resource
+
+This directory contains the Markdown and supporting files that comprise the N-API Resource website published at the following URL by GitHub Pages:
+
+https://nodejs.github.io/node-addon-examples/
+
+The website is genereated by [Gatsby](https://www.gatsbyjs.org) and published to this repository's `gh-pages` branch.
+
+## Objective
+
+The basic objective of this site is to publish additional useful information concerning the N-API technology that extends beyond the basic documentation.
+
+Ideally, pages published to this site should reference a working demo module that is also stored in this same repository. Features configured into the Gatsby project make embedding example source code fairly straightforward. 
+
+## Contributing
+
+Submissions are gratefully accepted. Simply fork the [node-addon-examples](https://github.com/nodejs/node-addon-examples) repository containing this directory, make your changes, and submit a PR. 
+
+All of the site's content is located in the `docs` directory. Besides the Markdown files, there is also the `toc.json` file that needs to be updated when pages are added or removed.
+
+### Frontmatter
+
+Each of the Markdown files includes front matter that Gatsby uses when formatting the site.
+
+| Tag     | Description                                                  |
+| ------- | ------------------------------------------------------------ |
+| `id`    | A unique identifying string for this page.                   |
+| `title` | The title of the page as shown at the top of the page itself. |
+| `prev`  | The `id` of the page to be shown as the Previous link at the bottom of the page. |
+| `next`  | The `id` of the page to be shown as the Next link at the bottom of the page. |
+
+The `prev` and `next` links can be omitted for the first and last pages in the set, respectively. 
+
+### Gatsby Basics
+
+This project assumes that Gatsby is installed globally. 
+
+```
+npm install -g gatsby-cli
+```
+
+Be sure to set `website` as the current working directory before working on the website. For example:
+
+```
+cd website
+```
+
+These commands are useful while working on the site:
+
+| Command          | Description                                                  |
+| ---------------- | ------------------------------------------------------------ |
+| `gatsby develop` | Start a hot-reloading preview site at `http://localhost:8000`. |
+| `gatsby build`   | Perform an optimized production build into the `public` folder. |
+| `gatsby serve`   | Start a local HTML server using the results from `gatsby build`. |
+
+### Embedding Source Code Samples
+
+For this project, Gatsby is configured to have the ability to copy example source code into the generated web pages. The advantage of this approach is that the web pages can be easliy regenerated whenever the source code files change. 
+
+Here's the pattern to follow for embedding example source code:
+
+```
+[**package.json**](https://github.com/nodejs/node-addon-examples/blob/master/object-wrap-demo/node-addon-api/package.json)
+
+`embed:object-wrap-demo/node-addon-api/package.json`
+```
+
+> This snippet is taken from `website/docs/getting-started/objectwrap.md`
+
+The path in the `embed` tag is relative to the main `node-addon-examples` directory, not the `website` directory. 
+

website/docs/about/uses.md

@@ -0,0 +1,19 @@
+---
+id: about.uses
+title: Uses for N-API
+prev: about.what
+---
+
+## An existing C/C++ library
+
+Perhaps the most popular use for N-API is making the capabilities of an existing C/C++ library available to JavaScript programmers. This permits you to leverage the investment you've already made in your existing code, making it available to a whole new population of JavaScript programmers and projects. 
+
+For many applications, the C/C++ code base is the reference implementation. N-API permits you to continue to refine and maintain your existing C/C++ code. Improvements to the C/C++ code are then easily transferred to the JavaScript users.  
+
+## Access to OS resources
+
+Some applications, like those built on [Electron](https://electronjs.org) or [NW.js](https://nwjs.io), can benefit from accessing system toolkits and APIs not currently available through Node. N-API facilities accessing these system resources. 
+
+## Computational tasks
+
+For low-powered devices, it may make sense to code computationally intensive tasks in C or C++ and then make that code available to JavaScript using N-API. Although in many cases Node's JavaScript runtime engine will eventually compile the JavaScript down to binary, N-API offers the ability to compile the C/C++ code just once and have the binary available to Node right from the start. 

website/docs/about/what.md

@@ -0,0 +1,35 @@
+---
+id: about.what
+title: What is N-API?
+next: about.uses
+---
+
+## Node.js
+
+[Node.js](https://nodejs.org/en/about/) is a command line application running on development and server systems, that encapsulates a JavaScript runtime engine along with other support code primarily targeted towards implementing command line tools and network server applications. It essentially permits you to run JavaScript on the server. It is supported on nearly all current hardware and software architectures. 
+
+## Node Modules
+
+Node encourages modular software development by supporting [Modules](https://nodejs.org/api/modules.html#modules_modules). Modules are essentially a colection of files and directories that conform to specific requirements. Some background information about creating Node modules can be found [here](https://docs.npmjs.com/creating-node-js-modules).
+
+One of the real benefits of adopting Node is the comprehensive ecosystem of Node modules available to developers. The largest collection of Node modules is available from [npm](https://www.npmjs.com). The `npm` command line tool is installed along with Node. 
+
+## Node Native Modules
+
+Besides modules written in JavaScript, Node also provides technology to enable the deveopment of Node modules written primarily in C and C++. This permits existing C and C++ libraries to be compiled into Node *native* modules that are virtually indistinguishable from those written entirely in JavaScript. 
+
+N-API is the technology that enables the development of Node native modules. 
+
+## N-API
+
+[N-API](https://nodejs.org/api/n-api.html#n_api_n_api) is a toolkit introduced in Node 8.0.0 that acts as an intermediary between C/C++ code and the Node JavaScript engine. It permits C/C++ code to access, create, and manipulate JavaScript objects as if they were created by JavaScript code. N-API is built into Node versions 8.0.0 and later and requires no further installation.
+
+There is another Node toolkit that predates N-API, [Native Abstractions for Node.js (NAN)](https://github.com/nodejs/nan) that serves a similar purpose. NAN is implemented using direct calls to the [Chrome V8](https://developers.google.com/v8/) that Node has historically used as its JavaScript engine. The disadvantage of this approach is that the NAN layer itself, as well as code that relies on it, needs to be updated every time the V8 engine used by Node is updated. 
+
+N-API, on the other hand, abstracts out its API from the underlying JavaScript engine. This provides two immediate benefits. The first is that N-API guarantees that the API will always be backward compatible. This means that a module you create today will continue to run on all future versions of Node without the need for running `npm install` again. Since N-API is ABI-stable, your module will continue to run even without recompilation. 
+
+The second benefit is that your module will continue to run even if Node's underlying JavaScript engine is changed. For example, there is a lot of interest in incorporating [Microsoft's ChakraCore](https://github.com/Microsoft/ChakraCore) JavaScript engine [into Node](https://github.com/nodejs/node-chakracore). Modules built on N-API will run on the ChakraCore engine without modification. In fact, they'll run without recompilation. 
+
+## node-addon-api
+
+An important adjunct to N-API, although not strictly a part of the main project, is the npm [`node-addon-api`](https://www.npmjs.com/package/node-addon-api) module. The purpose of this module is to raise the N-API API from the level of "C" up to "C++". For many users, the object model implemented by `node-addon-api` makes the effort of creating N-API modules much easier and enjoyable.