Merge pull request #73 from metacall/docs

Documentation Milestone

docs/autodoc.rst

@@ -1,8 +1,16 @@
 .. _autodoc:
- 
-kernel.py
+
+Source documentation
 =============
-
+
+kernel.py
+-----------------
 .. automodule:: kernel
   :members:
-  :undoc-members:
+  :undoc-members:
+
+install.py
+-----------------
+.. automodule:: install
+  :members:
+  :undoc-members:

docs/conf.py

@@ -20,9 +20,10 @@
 # ones.
 extensions = [
     "sphinx_rtd_theme",
-    "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/contributing.rst

@@ -0,0 +1,157 @@
+Contributing
+============
+
+Bug fixes, performance improvements, code formatting. There are a lot
+ways in which you can contribute! The issues list of a project is a
+great place to find something that you can help us with.
+
+To increase the chances of your contribution getting merged, please
+ensure that:
+
+-  You satisfy our code of conduct.
+-  Your code follows our coding guidelines.
+-  Your submission follows Vincent Driessen’s Git Branching System.
+-  Your pull request:
+
+   -  Passes all checks and has no conflicts.
+   -  Has a well-written title and message that briefly explains your
+      proposed changes.
+
+We welcome all kinds of bug reports, user feedback and feature requests!
+To get started with contributing for the very first time on GitHub, we
+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.
+
+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
+workstation and GitHub.
+
+Confirm authentication is working correctly with the following command:
+
+::
+
+   ssh -T git@github.com
+
+Fork and clone the repository
+-----------------------------
+
+You must fork and set up the MetaCall’s Jupyter Kernel repository on
+your workstation so that you can create PRs and contribute. These steps
+must only be performed during initial setup.
+
+1. Fork the https://github.com/metacall/jupyter-kernel repository into
+   your GitHub account from the GitHub UI. You can do this by clicking
+   on **Fork** in the upper right-hand corner.
+2. In the terminal on your workstation, change into the directory where
+   you want to clone the forked repository.
+3. Clone the forked repository onto your workstation with the following
+   command, replacing with your actual GitHub username:
+   ``git clone git@github.com:<user_name>/jupyter-kernel.git``
+4. Change into the directory for the local repository you just cloned.
+   ``cd jupyter-kernel``
+5. Add an upstream pointer back to the MetaCall’s remote repository, in
+   this case ``jupyter-kernel``.
+   ``git remote add upstream git@github.com:metacall/jupyter-kernel.git``
+   This ensures that you are tracking the remote repository to keep your
+   local repository in sync with it.
+
+Making the changes
+------------------
+
+Follow the install instructions to setup the project locally. After you
+are done making the changes, make sure to run Black and Flake8 for code
+linting and formatting respectively. We have a pre-configured Flake8
+configuration and once you run ``black`` against the source directory or
+file, run Flake8 to verify that linting checks pass:
+
+::
+
+   flake8
+
+Optionally, we would also like the Continous Integration to pass
+successfully and would advise for the usage of ``act`` for running the
+workflows locally. ``act`` is a tool offered by Nektos which provides a
+handy way to run GitHub Actions locally using Docker.
+
+``act`` can be set up locally with Homebrew, Chocolatey or even a simple
+BASH script. To set it up using the BASH script, just push the following
+command on your terminal:
+
+::
+
+   curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+Next step is to define the custom image that we can use to run our
+actions locally. ``act`` provides a micro, medium and larger Docker
+image for Ubuntu GitHub runner. ``act`` does not support Windows and
+macOS images yet.
+
+While running ``act`` for the first time, we can define the image that
+we would like to utilize for our local CI runs. The configuration is
+saved inside the ``~/.actrc`` file.
+
+In the cloned repository, while running ``act`` for the first time, it
+will find the ``./.github/workflows`` and all the workflows present. To
+checkout the jobs listed as part of the GitHub Actions CI, push the
+following command:
+
+::
+
+   act -l
+
+It will list all the jobs and you can pick up the particular jobs you
+wish to run. If you are looking to run a particular job, push in the
+following command:
+
+::
+
+   act -j <JOB_NAME>
+
+To run the job in dry run, push in the following command:
+
+::
+
+   act -n
+
+To run the job with verbose logging, push in the following command:
+
+::
+
+   act -v
+
+To reuse the containers in ``act`` to maintain state, push in the
+following command:
+
+::
+
+   act -j <JOB_NAME> --bind --reuse
+
+If the workflow is running successfully, you can now be confident about
+your changes and be ready to send a Pull Request for the same.
+
+Sending a Pull Request
+----------------------
+
+When your work is ready and complies with the project conventions,
+upload your changes to your fork, by making a clean commit. Make sure
+that the changes being proposed are from a branch and not the
+``master``.
+
+::
+
+   git push -u origin Branch_Name
+
+Go to your repository on your browser and click on **Compare** and pull
+requests. Add a title and description to your pull request that explains
+your contribution. Voila! Your Pull Request has been submitted and will
+be reviewed by the maintainers and merged.
+
+.. _here: https://github.com/metacall/jupyter-kernel/blob/master/examples

docs/getting-started.rst

@@ -0,0 +1,98 @@
+Getting Started
+===========
+
+Starting a notebook
+-------------------
+
+To start a notebook, type in a terminal:
+
+::
+
+   jupyter notebook
+
+Your default webbrowser should open with a list of the files in the
+current directory. Choose ``New->metacall_kernel`` to open a new
+notebook of type ``metacall_kernel``.
+
+You can also start a nootbook directly from the commandline using our
+launcher script:
+
+::
+
+   python3 -m metacall_jupyter.launcher
+
+Closing a notebook
+------------------
+
+To close the notebook, choose:
+
+::
+
+   File -> Close and Halt
+
+from the menu.
+
+Note that simply closing the browser tab does not close the notebook or
+the running MetaCall Polyglot REPL subprocess(es) behind it. You can
+reopen the tab by clicking on the name of your notebook (next to the
+then green icon).
+
+It is also possible to kill the MetaCall REPL subprocess(es) running
+behind the notebook by clicking on the Shutdown button in the running
+notebook section of your Jupyter session.
+
+You can optionally use the programmatic way to shutdown by pushing it in
+the cell and executing it:
+
+::
+
+   $shutdown
+
+It will gracefully kill the running subprocess and you can safely exit
+from the notebook.
+
+Running a notebook
+------------------
+
+MetaCall Jupyter kernel supports a few commands that allows you to
+interact with the MetaCall Polyglot REPL to load and execute code in
+different languages. The other commands and magics allow you to load
+foreign functions on the language, interact with the shell and inspect
+the meta-object protocol.
+
+You can check-out all the available functionalities using the ``$help``
+command on the cell and execute it. You will get the following output:
+
+::
+
+   1. ! : Run a Shell Command on the MetaCall Jupyter Kernel
+   2. $shutdown : Shutdown the MetaCall Jupyter Kernel
+   3. $inspect : Inspects the MetaCall to check all loaded functions
+   4. $loadfile: Loads a file onto the MetaCall which can be evaluated
+   5. $newfile: Creates a new file and appends the code mentioned below
+   6. %repl <tag>: Switch from different REPL (available tags: node, py)
+   7. >lang: Execute scripts using the MetaCall exec by saving them in a temporary file (available languages: python, javascript)
+   8. $loadcell <tag>: Loads a function onto the MetaCall to be evaluated
+   9. $help: Check all the commands and tags you can use while accessing the MetaCall Kernel
+   10. $available: Checks all the available REPLs on the Kernel
+
+You can load a REPL, by just passing ``%repl <tag>`` where you can
+replace ``<tag>`` with the languages available. You can check-out the
+available languages through the ``$available`` command.
+
+Exporting the notebook
+----------------------
+
+You can export a reproducible copy of the Notebook by choosing:
+
+::
+
+   File -> Download as
+
+You can download the Notebook in a Notebook (``.ipynb``), PDF, HTML,
+Markdown and more formats easily. Make sure to save and checkpoint to
+ensure a reproducible copy on your own local machine:
+
+::
+
+   File -> Save and Checkpoint

docs/index.rst

@@ -6,17 +6,50 @@
 Welcome to MetaCall Jupyter Kernel's documentation!
 ===================================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+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.
 
-   autodoc
+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.
 
-Indices and tables
-==================
+.. _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
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   getting-started
+   usage
+   autodoc
+   contributing