docs: add index docs

docs/contributing.rst

@@ -24,14 +24,14 @@ have a few steps outlined for you.
 Create a GitHub account
 -----------------------
 
-Before you can contribute to MetaCall’s Jupyter Kernel, you must `sign
-up for a GitHub account`_.
+Before you can contribute to MetaCall’s Jupyter Kernel, you must sign up
+for a GitHub account.
 
 Set up authentication
 ---------------------
 
-When you have your account set up, follow the instructions to `generate
-and set up SSH keys on GitHub`_ for proper authentication between your
+When you have your account set up, follow the instructions to generate
+and set up SSH keys on GitHub for proper authentication between your
 workstation and GitHub.
 
 Confirm authentication is working correctly with the following command:

docs/index.rst

@@ -6,8 +6,47 @@
 Welcome to MetaCall Jupyter Kernel's documentation!
 ===================================================
 
+MetaCall Jupyter Kernel is an open-source wrapper kernel that implements
+cross-language function calls through the `MetaCall Core`_ and the
+`Polyglot REPL`_. MetaCall Core is an open-source library that brings
+the polyglot programming experience to Developers. With MetaCall,
+developers can embed different programming languages through an
+easy-to-use high-level API.
+
+The Kernel exposes the MetaCall Core API which can be loaded and
+launched through a Jupyter Notebook interface. With this Notebook, the
+users can try out writing, mixing and embedding code in different
+programming languages.
+
+When a `Jupyter`_ notebook of type ``metacall_kernel`` is opened, the
+Kernel starts a new `Polyglot REPL`_ subprocess. In fact, the
+``metacall_kernel`` makes the kernel behave like a wrapper over the
+`Polyglot REPL`_ subprocess where standard input is imparted and the
+standard output is fetched and displayed on the client interface.
+
+To put it in a nutshell, ``metacall_kernel`` essentially comprises three
+files which has to be installed:
+
+-  **Kernel Spec**: `kernel.json`_
+-  **Wrapper Kernel**: `kernel.py`_
+-  **REPL subprocess**: `repl.js`_
+
+Cell input in the Jupyter notebook is taken by `kernel.py`_ and sent via
+`repl.js`_ to `Polyglot REPL`_ running through the subprocess. Output
+from `Polyglot REPL`_ is collected by `repl.js`_ and given back to
+`kernel.py`_ where it is analysed and transformed into an output format
+that the `Jupyter`_ notebook understands, and thus eventually displayed.
+
+.. _kernel.json: https://github.com/metacall/jupyter-kernel/blob/master/metacall_jupyter/install.py
+.. _kernel.py: https://github.com/metacall/jupyter-kernel/blob/master/metacall_jupyter/kernel.py
+.. _repl.js: https://github.com/metacall/jupyter-kernel/blob/master/repl.js
+.. _Jupyter: https://jupyter.org/
+.. _MetaCall Core: https://github.com/metacall/core
+.. _Polyglot REPL: https://github.com/metacall/polyglot-repl
+
 .. toctree::
-   :hidden:
+   :maxdepth: 2
+   :caption: Contents:
 
    installation
    contributing

docs/installation.rst

@@ -51,8 +51,7 @@ Start your Jupyter Notebook by pushing the following command:
    python3 -m metacall_jupyter.launcher
 
 You can pick ``metacall_jupyter`` from the drop-down options and start
-working with the Jupyter Notebook interface. Example Notebook are found
-`here`_.
+working with the Jupyter Notebook interface.
 
 Building the Kernel
 ~~~~~~~~~~~~~~~~~~~
@@ -66,6 +65,21 @@ changes, run through your changes:
    python3 -m metacall_jupyter.install
    python3 -m metacall_jupyter.launcher
 
+Docker setup
+~~~~~~~~~~~~~
+
+Build the image:
+
+::
+
+   docker build -t metacall/jupyter .
+
+Run the image:
+
+::
+
+   docker run --rm --network=host -it metacall/jupyter
+
 Run the Tests
 ~~~~~~~~~~~~~