Convert docs to Markdown (#125)

* Convert docs to Markdown

* Minor doc edits

Author: jtpio

docs/build-environment.yml

@@ -8,11 +8,12 @@ dependencies:
   - pip
   - click
   - typer
+  - myst-parser
   - pydata-sphinx-theme
   - yarn
-  - jupyterlab
+  - jupyterlab >=3.5.3,<3.6
+  - jupyterlite-core >=0.1.0,<0.2.0
   - empack >=2.0.9,<3
   - pip:
-    - jupyterlite-core==0.1.0
     - jupyterlite-sphinx
     - ..

docs/conf.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 
 extensions = [
-    'jupyterlite_sphinx'
+    'jupyterlite_sphinx',
+    'myst_parser',
 ]
 
 master_doc = 'index'

docs/configuration.md

@@ -0,0 +1,56 @@
+(configuration)=
+
+# Configuration
+
+## Pre-installed packages
+
+`xeus-python` allows you to pre-install packages in the Python runtime. You can pre-install packages by adding an `environment.yml` file in the JupyterLite build directory, this file will be found automatically by xeus-python which will pre-build the environment when running `jupyter lite build`.
+
+Furthermore, this automatically installs any labextension that it founds, for example installing ipyleaflet will make ipyleaflet work without the need to manually install the jupyter-leaflet labextension.
+
+Say you want to install `NumPy`, `Matplotlib` and `ipycanvas`, it can be done by creating the `environment.yml` file with the following content:
+
+```
+name: xeus-python-kernel
+channels:
+- https://repo.mamba.pm/emscripten-forge
+- https://repo.mamba.pm/conda-forge
+dependencies:
+- numpy
+- matplotlib
+- ipycanvas
+```
+
+Then you only need to build JupyterLite:
+
+```
+jupyter lite build
+```
+
+You can also pick another name for that environment file (*e.g.* `custom.yml`), by doing so, you will need to specify that name to xeus-python:
+
+```
+jupyter lite build --XeusPythonEnv.environment_file=custom.yml
+```
+
+```{note}
+It is common to provide `pip` dependencies in a conda environment file. This is currently **not supported** by xeus-python, but there is a [work-in-progress](https://github.com/jupyterlite/xeus-python-kernel/pull/102) to support it.
+```
+
+Then those packages are usable directly:
+
+```{eval-rst}
+.. replite::
+   :kernel: xeus-python
+   :height: 600px
+   :prompt: Try it!
+
+   %matplotlib inline
+
+   import matplotlib.pyplot as plt
+   import numpy as np
+
+   fig = plt.figure()
+   plt.plot(np.sin(np.linspace(0, 20, 100)))
+   plt.show();
+```

docs/configuration.rst

@@ -0,0 +1,14 @@
+(deploy)=
+
+# Deploy your own
+
+## On Github Pages
+
+In order to make your own JupyterLite deployment, you can use the  [xeus-python-demo repository template](https://github.com/jupyterlite/xeus-python-demo)
+that allows you to easily make a JupyteLite deployment on Github pages with xeus-python as default kernel.
+
+This template repository contains an `environment.yml` file where you can specify the packages you need. You can also add Notebooks to the `content` folder.
+
+## In Sphinx documentation
+
+You can make a JupyterLite deployment with xeus-python installed using the [jupyterlite-sphinx extension](https://github.com/jupyterlite/jupyterlite-sphinx)

docs/deploy.md

@@ -0,0 +1,36 @@
+# xeus-python in JupyterLite 🚀🪐
+
+The [xeus-python](https://github.com/jupyter-xeus/xeus-python) kernel compiled to WebAssembly and installable in JupyterLite!
+
+Features:
+
+- all IPython features included (magics, matplotlib inline `etc`)
+- code completion
+- code inspection
+- interactive widgets (ipywidgets, ipyleaflet, bqplot, ipycanvas `etc`)
+- JupyterLite custom file-system mounting
+
+How does it compare to the [Pyodide kernel](https://github.com/jupyterlite/pyodide-kernel) for JupyterLite?
+
+- `from time import sleep` works!
+- starts faster!
+- it's lighter by default!
+- pre-installed packages! No more piplite (see {ref}`configuration` page)
+- no more piplite, but we will be working on a mambalite, stay tuned :D
+
+```{eval-rst}
+.. replite::
+   :kernel: xeus-python
+   :height: 600px
+
+   print("Hello from xeus-python!")
+```
+
+```{toctree}
+:caption: Usage
+:maxdepth: 2
+
+installation
+deploy
+configuration
+```

docs/deploy.rst

@@ -0,0 +1,15 @@
+(installation)=
+
+# Installation
+
+You can install `jupyterlite-xeus-python` with `pip`:
+
+```
+pip install jupyterlite-xeus-python
+```
+
+Once you have installed `jupyterlite-xeus-python`, you can use it as a kernel in JupyterLite. You can use the `jupyter lite` command line interface to build a JupyterLite application to start using the `xeus-python` kernel:
+
+```bash
+jupyter lite build
+```