Update documentation

.gitignore

@@ -4,3 +4,10 @@ node_modules/
 res/.ipynb_checkpoints/
 res/test.ipynb
 res/test-complete.ipynb
+res/test-graphics.ipynb
+res/test-inspect.ipynb
+res/test-mime-global.ipynb
+res/test-mime-property.ipynb
+res/image.jpg
+res/image.png
+res/image.svg

.npmignore

@@ -6,3 +6,10 @@ node_modules/
 res/.ipynb_checkpoints/
 res/test.ipynb
 res/test-complete.ipynb
+res/test-graphics.ipynb
+res/test-inspect.ipynb
+res/test-mime-global.ipynb
+res/test-mime-property.ipynb
+res/image.jpg
+res/image.png
+res/image.svg

CONTRIBUTING.md

@@ -2,42 +2,61 @@
 
 First of all, thank you for taking the time to contribute.
 
-Here, you will find important information for contributing to this project.
+Here, you will find relevant information for contributing to this project.
 
-## Reporting an issue
+## Issue tracker
 
-Please, feel free to report any issues you encounter or any enhancements you
-would like to see implemented. To facilitate the process of fixing an issue,
-please, include the following information in your report:
+Please, feel free to use the [issue
+tracker](https://github.com/n-riesco/ijavascript/issues) to report any problems
+you encounter or any enhancements you would like to see implemented. To
+facilitate the process of fixing a problem, please, include the following
+information in your report:
 
-- npm version. Please, run the command:
+- IJavascript version. Please, run the command:
+
+```sh
+npm list ijavascript
+```
+
+- npm version:
 
 ```sh
 npm version
 ```
 
+- IPython version:
+
+```sh
+ipython --version
+```
+
 - Operating system. In most modern linux distributions, it is enough to run:
 
 ```sh
 lsb_realease -sd
 ```
 
-## Sending Pull Requests
+## Code contributions
+
+- Please, open an issue in the [issue
+  tracker](https://github.com/n-riesco/ijavascript/issues).
 
 - Pull requests will be distributed under the terms in the LICENSE file. Hence,
   before accepting any pull requests, it is important that the copyright holder
   of a pull request acknowledges their consent. To express this consent, please,
   ensure the AUTHORS file has been updated accordingly.
 
-## Coding Guidelines
+## Coding guidelines
 
 - For the sake of readability, please, ensure the coding style of your pull
   requests is consistent with this project: lowerCamelCaseNaming,
-  CONSTANTS_NAMING, 4-space indent, collapsed brackets... As a guideline, I will
-  try to follow the recommendations proposed in the [Google Javascript Style
-  Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml).
+  CONSTANTS_NAMING, 4-space indent, collapsed brackets...
 
-- The IPython protocol uses underscores, `_`, in their the naming convention (as
+- The IPython protocol uses underscores (`_`) in their the naming convention (as
   recommended in [PEP8](https://www.python.org/dev/peps/pep-0008/)). For these
   names, I find more readable to keep the original naming (although, if possible
   limited to a local scope).
+
+- The source code in IJavascript is annotated using
+  [JSDoc](https://github.com/jsdoc3/jsdoc). The generated documentation can be
+  found [here](https://github.com/n-riesco/ijavascript/tree/master/doc/jsdoc).

README.md

@@ -14,79 +14,33 @@ There are kernels available for [Python](http://ipython.org/notebook.html),
 [Julia](https://github.com/JuliaLang/IJulia.jl),
 [Ruby](https://github.com/minad/iruby),
 [Haskell](https://github.com/gibiansky/IHaskell) and [many
-others](https://github.com/ipython/ipython/wiki/IPython-kernels-for-other-languages).
+other languages](https://github.com/ipython/ipython/wiki/IPython-kernels-for-other-languages).
 
-IJavascript implements the latest stable specification of the protocol, [version
-4.1](http://ipython.org/ipython-doc/stable/development/messaging.html).  This
-specification will be updated to [version
-5.0](http://ipython.org/ipython-doc/dev/development/messaging.html) in the
-next release of IPython.
+## Main Features
 
-A repository of IPython notebooks can be found
-[here](http://nbviewer.ipython.org/).
-
-## Prerequisites
-
-The prerequisites vary from platform to platform.
-
-### Debian and Ubuntu
-In recent Debian and Ubuntu distributions, it's enough to run the following
-command:
-
-```sh
-sudo apt-get install nodejs-legacy npm ipython ipython-notebook libzmq-dev
-```
-
-#### Ubuntu 12.04
-
-In Ubuntu 12.04, both `node.js` and `ipython` need upgrading to a recent
-version:
-
-```sh
-sudo apt-get install libzmq-dev python-dev python-pip g++ curl
-curl -sL https://deb.nodesource.com/setup | sudo bash -
-sudo apt-get install -y nodejs
-sudo pip install --upgrade ipython jinja2 tornado jsonschema pyzmq
-```
-
-The instructions for upgrading `node.js` have been adapted from those found
-[here](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#debian-and-ubuntu-based-linux-distributions).
-
-### Other Platforms
-
-For other platforms, instructions may be found at
-[nodejs.org/download](http://nodejs.org/download/),
-[ipython.org/install](http://ipython.org/install.html) and
-[zeromq.org/intro:get-the-software](http://zeromq.org/intro:get-the-software).
+- Run Javascript code within a `node.js` session
+- [Autocompletion](doc/complete.md): press `TAB` to complete keywords and object
+  properties
+- [Object inspection](doc/inspect.md): press `Shift-TAB` to inspect an object
+  and show its content or, if available, its documentation
+- [Graphical output](doc/graphics.md) for `HTML`, `PNG`, ...
 
 ## Installation
 
-To install IJavascript globally (i.e. for all users in the system), run:
+The instructions to install IJavascript are platform-dependent. For example, in
+Ubuntu 14.04, IJavascript and its prerequisites can be installed simply by
+running:
 
 ```sh
+sudo apt-get install nodejs-legacy npm ipython ipython-notebook libzmq-dev
 sudo npm install -g ijavascript
 ```
 
-To install locally, run:
-
-```sh
-npm install ijavascript
-```
-
-In Debian and Ubuntu distributions, the above command will install the
-executable `ijs` in the folder `~/node_modules/.bin/`. You may want to add this
-folder to your PATH:
-
-```sh
-echo \"PATH=\"\$HOME/node_modules/.bin\" >> ~/.profile
-```
-
-Note that the above change won't take effect until you log out of the current
-session.
+For other platforms, please, refer to the [installation notes](doc/install.md).
 
 ## Usage
 
-To start an IPython notebook session with the Javascript kernel, simply run:
+To start an IPython notebook session with the IJavascript kernel, run:
 
 ```sh
 ijs
@@ -97,29 +51,22 @@ browser:
 
 ![Screenshot: IPython Notebook Dashboard](res/screenshot-dashboard-home.png)
 
-By default, the dashboard opens the notebooks in the current working folder. The
-flag `--notebook-dir=path/to/another/folder` can be used to open the dashboard
-at a different folder:
-
-```sh
-ijs --notebook-dir=path/to/another/folder
-```
-
-![Screenshot: IPython Notebook --notebook-dir](res/screenshot-dashboard-dir.png)
-
-Here's a sample notebook that makes use of the Javascript kernel:
+Here's a sample notebook that makes use of the IJavascript kernel:
 
 ![Screenshot: Notebook Hello Sample](res/screenshot-notebook-hello.png)
 
-Documentation on other flags, can be found using IPython's notebook help:
+Please, refer to the [usage notes](doc/usage.md) for further details.
 
-```sh
-ipython notebook help
-```
+# Contributions
+
+First of all, thank you for taking the time to contribute. Please, read
+[CONTRIBUTING.md](CONTRIBUTING.md) and use the
+[issue tracker](https://github.com/n-riesco/ijavascript/issues) for any
+contributions: support requests, bug reports, enhancement requests, pull
+requests, ...
 
-## TO DO
+# TO DO
 
 - Add tests
 - Complete the implementation of IPython's messaging protocol v4.1
 - Implement Jupyter's messaging protocol v5.0
-- Provide graphical output

doc/complete.md

@@ -0,0 +1,17 @@
+# `TAB` completion
+
+IJavascript provides a completion list for both Javascript keywords and object
+properties. This completion list is shown when `TAB` is pressed:
+
+![Screenshot: TAB complete
+(keywords)](../res/screenshot-notebook-complete-keyword.png)
+
+It can be used to complete object properties accessed using the dot operator
+(`.`):
+
+![Screenshot: TAB complete (dot)](../res/screenshot-notebook-complete-dot.png)
+
+or the bracket operator (`[]`):
+
+![Screenshot: TAB complete
+(bracket)](../res/screenshot-notebook-complete-bracket.png)

doc/graphics.md

@@ -0,0 +1,70 @@
+# Graphical output
+
+IJavascript provides a number of global variables to produce a graphical output.
+
+## Text formats
+
+IJavascript can output `HTML` and `SVG`.
+
+### `$$html$$`
+
+To output `HTML` simply assign a string with the HTML to the global variable
+`$$html$$`. See the example below:
+
+```javascript
+$$html$$ = "<div style='background-color:olive;width:50px;height:50px'></div>"
+```
+
+![Screenshot: HTML output](../res/screenshot-notebook-html.png)
+
+### `$$svg$$`
+
+Similarly, it is possible to output `SVG` by assigning a string to the global
+variable `$$svg$$`:
+
+```javascript
+$$svg$$ = "<svg><rect width=80 height=80 style='fill: orange;'/></svg>"
+```
+
+![Screenshot: SVG output](../res/screenshot-notebook-svg.png)
+
+## Binary formats
+
+IJavascript can also output pictures in `PNG` and `JPEG` formats. However, this
+formats are binary and need to be encoded in `base64`. See how in the following
+examples.
+
+### `$$png$$`
+
+In the below example, a `PNG` file is read, then encoded in `base64` and finally
+assigned to the global variable `$$png$$`:
+
+```javascript
+$$png$$ = fs.readFileSync("image.png").toString("base64");
+```
+
+![Screenshot: PNG output](../res/screenshot-notebook-png.png)
+
+### `$$jpeg$$`
+
+Similarly with `JPEG` files and the global variable `$$jpeg$$`:
+
+```javascript
+$$jpeg$$ = fs.readFileSync("image.jpg").toString("base64");
+```
+
+![Screenshot: JPEG output](../res/screenshot-notebook-jpeg.png)
+
+## MIME output
+
+IJavascript also provides the global variable `$$mime$$` to produce an output in
+any other format understood by the IPython frontend. Following is an example
+where instead of assigning an HTML string to the global variable `$$html$$`, the
+global variable `$$mime$$` is assigned an object with the HTML string assigned
+to the property `"text/html"`:
+
+```javascript
+$$mime$$ = {"text/html": "<div style='background-color:olive;width:50px;height:50px'></div>"};
+```
+
+![Screenshot: MIME output](../res/screenshot-notebook-mime.png)

doc/inspect.md

@@ -0,0 +1,15 @@
+# `Shift-TAB` object inspection
+
+IJavascript has the capability of inspection the value of an object or its
+documentation if available.
+
+To show the content of a variable, move the cursor to the end of that variable
+and press `Shift-TAB`:
+
+![Screenshot: Shift-Tab inspect
+(value)](../res/screenshot-notebook-inspect-value.png)
+
+When available, IJavascript will show the associated documentation instead:
+
+![Screenshot: Shift-Tab inspect
+(doc)](../res/screenshot-notebook-inspect-doc.png)