Improve documentationorigin/test-utils

6 files changed, 148 insertions, 17 deletions

diff --git a/docs/README.md b/docs/README.md
index 272896d..781f2aa 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,4 @@
-# GitBook Toolchain Documentation
+![GitBook Toolchain Documentation](./images/banner.png)
 
 This document aims to be a comprehensive guide to GitBook. It contains the full documentation for version **{{ book.version }}**. Help for GitBook.com specific questions can be found at [help.gitbook.com](https://help.gitbook.com).
 
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index e3d8d67..7cb21f0 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -44,10 +44,16 @@
 
 ### Plugin Development
 
-* [Introduction](./api/README.md)
-* [Node](./api/node.md)
+* [Creating a plugin](./api/README.md)
 * [Connect to the context](./api/connect.md)
 * [Components](./api/components.md)
+* [Node APIs](./api/node.md)
+
+### Internals
+
+* [Using programmatically](./internals/README.md)
+* [Browser environment](./internals/browser.md)
+* [APIs](./internals/api.md)
 
 --
 
diff --git a/docs/internals/README.md b/docs/internals/README.md
new file mode 100644
index 0000000..7ee13c3
--- /dev/null
+++ b/docs/internals/README.md
@@ -0,0 +1,33 @@
+# Using GitBook programmatically
+
+GitBook is mainly designed to work as a command line utility, but it can also be integrated into javascript application (Node.js or browser).
+
+Its API can be used for parsing a book, modifying the structure of a book, or generating outputs.
+
+### Installation
+
+```
+$ npm install gitbook
+```
+
+### Design
+
+The GitBook Core API is built around **promises** and **immutable** models.
+
+### Example
+
+```js
+const GitBook = require('gitbook');
+
+// Create a filesystem interface
+const fs = GitBook.createNodeFS(__dirname + '/mybook');
+
+// Create a book instance
+const book = GitBook.Book.createForFS(fs);
+
+// Parse it
+GitBook.Parse.parseBook(book)
+.then(newBook => {
+    console.log('Done!');
+})
+```
diff --git a/docs/internals/api.md b/docs/internals/api.md
new file mode 100644
index 0000000..0077adc
--- /dev/null
+++ b/docs/internals/api.md
@@ -0,0 +1,59 @@
+# APIs
+
+- [Parsing](#parsing)
+- [Manipulation](#manipulation)
+- [Generation](#generation)
+
+## Parsing
+
+### `GitBook.Parse.parseBook`
+`GitBook.Parse.parseBook(book: Book): Promise<Book>`
+
+Parse the whole book (languages, readme, summary), it returns a complete version of the book instance.
+
+### `GitBook.Parse.parse[Summary|Glossary|Languages]`
+`GitBook.Parse.parse[X](book: Book): Promise<Book>`
+
+Parse a specific part of the book only, it returns a book instance with the updated part.
+
+These methods can be used in combinaison with a file watch to avoid parsing the whole books when a file is modified.
+
+## Manipulation
+
+### `GitBook.SummaryModifier.toText`
+`GitBook.SummaryModifier.toText(summary: Summary, fileExt: String?): String`
+
+Serialize the summary as a string, the argument `fileExt` can be used to specify the parser:
+
+```js
+const textDefault = GitBook.SummaryModifier.toText(summary);
+const textAdoc = GitBook.SummaryModifier.toText(summary, '.adoc');
+const textAdoc = GitBook.SummaryModifier.toText(summary, '.md');
+```
+
+### `GitBook.SummaryModifier.insertArticle`
+`GitBook.SummaryModifier.insertArticle(summary: Summary, article: Article, level: String): Summary`
+
+Insert a summary `article` after the article identified with `level`.
+
+### `GitBook.SummaryModifier.unshiftArticle`
+`GitBook.SummaryModifier.unshiftArticle(summary: Summary, article: Article): Summary`
+
+Insert a summary `article` at the beginning of it.
+
+### `GitBook.SummaryModifier.removeArticle`
+`GitBook.SummaryModifier.removeArticle(summary: Summary, article: Article|String): Summary`
+
+Remove an article from the summary.
+
+## Generation
+
+### `GitBook.Output.getGenerator`
+`GitBook.Output.getGenerator(type: String): Generator`
+
+Return a generator, `type` may be one of `["website", "json", "ebook"]`.
+
+### `GitBook.Output.generate`
+`GitBook.Output.generate(generator: Generator, book: Book): Output`
+
+Generate a book using a generator.
diff --git a/docs/internals/browser.md b/docs/internals/browser.md
new file mode 100644
index 0000000..1ea51bb
--- /dev/null
+++ b/docs/internals/browser.md
@@ -0,0 +1,37 @@
+# Parsing GitBook in the browser
+
+The GitBook core API can be integrated in applications running in a browser environment (web application or Electon). One good example is the official [GitBook Editor](https://www.gitbook.com/editor), built using Electon and the GitBook core library.
+
+The `gitbook` package can be imported during a browserify/webpack build. Only the parsing components will be bundled. **Generating an output** is not possible on a browser environment.
+
+### Mocking the filesystem
+
+Since books are a composition of multiple files in a directory, the parsing requires some kind of filesystem interface.
+
+On a node.js environment, GitBook provides a method to create the right interface: `GitBook.createNodeFS(bookFolder: String): FS`.
+
+On a browser application, the interface depends mostly on your application design.
+
+```js
+
+const appFS = GitBook.FS.create({
+    // (String): Boolean
+    fsExists(filePath) {
+        ...
+    },
+    // (String): Buffer
+    fsReadFile(filePath) {
+        ...
+    },
+    // (String): { mtime: Date }
+    fsStatFile(filePath) {
+        ...
+    },
+    // (String): Array<String>
+    fsReadDir(filePath) {
+        ...
+    }
+});
+```
+
+[Checkout the core FS interfaces](https://github.com/GitbookIO/gitbook/tree/master/packages/gitbook/src/fs) for greater example.
diff --git a/docs/setup.md b/docs/setup.md
index 9300678..ce5e0ca 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -2,24 +2,18 @@
 
 Getting GitBook installed and ready-to-go should only take a few minutes.
 
-### GitBook.com
+This page describe the process for running the toolchain locally. The easiest for writing and hosting your content is to use [GitBook.com](https://www.gitbook.com) and the [GitBook Editor](https://www.gitbook.com/editor).
 
-[GitBook.com](https://www.gitbook.com) is an easy to use solution to write, publish and host books. It is the easiest solution for publishing your content and collaborating on it.
-
-It integrates well with the [GitBook Editor](https://www.gitbook.com/editor).
-
-### Local Installation
-
-##### Requirements
+### Requirements
 
 Installing GitBook is easy and straightforward. Your system just needs to meet these two requirements:
 
-* NodeJS (v4.0.0 and above is recommended)
+* Node.js (v4.0.0 and above is recommended)
 * Windows, Linux, Unix, or Mac OS X
 
-##### Install with NPM
+### Install with NPM
 
-The best way to install GitBook is via **NPM**. At the terminal prompt, simply run the following command to install GitBook:
+The best way to install GitBook is via **NPM** (or **Yarn**). At the terminal prompt, simply run the following command to install GitBook:
 
 ```
 $ npm install gitbook-cli -g
@@ -27,7 +21,7 @@ $ npm install gitbook-cli -g
 
 `gitbook-cli` is an utility to install and use multiple versions of GitBook on the same system. It will automatically install the required version of GitBook to build a book.
 
-##### Create a book
+### Create a book
 
 GitBook can setup a boilerplate book:
 
@@ -37,6 +31,8 @@ $ gitbook init
 
 If you wish to create the book into a new directory, you can do so by running `gitbook init ./directory`
 
+### Preview your website
+
 Preview and serve your book using:
 
 ```
@@ -49,7 +45,7 @@ Or build the static website using:
 $ gitbook build
 ```
 
-##### Install pre-releases
+### Install pre-releases
 
 `gitbook-cli` makes it easy to download and install other versions of GitBook to test with your book:
 
@@ -59,7 +55,7 @@ $ gitbook fetch beta
 
 Use `gitbook ls-remote` to list remote versions available for install.
 
-##### Debugging
+### Debugging
 
 You can use the options `--log=debug` and `--debug` to get better error messages (with stack trace). For example: