Add changelog to the docs, more markdown

docs/conf.py

@@ -1,4 +1,11 @@
 # -*- coding: utf-8 -*-
+import shutil
+
+from pathlib import Path
+
+HERE = Path(__file__).parent
+ROOT = HERE.parent
+
 
 extensions = [
     'jupyterlite_sphinx',
@@ -28,4 +35,5 @@
     ]
 }
 
-
+# Copy the markdown file here
+shutil.copy(ROOT / "CHANGELOG.md", HERE / "changelog.md")

docs/configuration.md

@@ -0,0 +1,75 @@
+# Configuration
+
+JupyterLite-sphinx can be configured in your `conf.py` file by setting some global Python variables:
+
+## JupyterLite content
+
+You can embed custom content (notebooks and data files) in your JupyterLite build by providing the following config:
+
+```python
+jupyterlite_contents = ["./path/to/my/notebooks/", "my_other_notebook.ipynb"]
+```
+
+`jupyterlite_contents` can be a string or a list of strings. Each string is expanded using the Python `glob.glob` function with its recursive option. See the [glob documentation](https://docs.python.org/3/library/glob.html#glob.glob) and the [wildcard pattern documentation](https://docs.python.org/3/library/fnmatch.html#fnmatch.fnmatch) for more details.
+
+## JupyterLite dir
+
+By default, jupyterlite-sphinx runs the `jupyter lite build` command in a temporary directory, you can overwrite this behavior and ask jupyterlite to build in a given directory:
+
+```python
+# Build in the current directory
+jupyterlite_dir = "."
+```
+
+This allows for jupyterlite to automatically pick-up some paths <https://jupyterlite.readthedocs.io/en/latest/reference/cli.html#the-lite-dir>
+
+## JupyterLite config
+
+You can provide [custom configuration](https://jupyterlite.readthedocs.io/en/latest/howto/index.html#configuring-a-jupyterlite-deployment)
+to your JupyterLite deployment.
+
+For example, if you want to have bqplot working in this deployment, you need to install the bqplot federated extension
+and you can serve the bqplot wheel to `piplite`, this is done by telling your `conf.py` where to look for the jupyterlite config:
+
+```python
+jupyterlite_config = "jupyterlite_config.json"
+```
+
+The `jupyterlite_config.json` containing the following:
+
+```json
+{
+    "LiteBuildConfig": {
+        "federated_extensions": [
+            "https://conda.anaconda.org/conda-forge/noarch/bqplot-0.12.33-pyhd8ed1ab_0.tar.bz2",
+        ],
+        "ignore_sys_prefix": true
+    }
+    "PipliteAddon": {
+        "piplite_urls": [
+            "https://files.pythonhosted.org/packages/py2.py3/b/bqplot/bqplot-0.12.33-py2.py3-none-any.whl",
+        ]
+    }
+}
+```
+
+Then you should be able to show Notebooks working with bqplot!
+
+```rst
+.. retrolite:: bqplot.ipynb
+```
+
+```{eval-rst}
+.. retrolite:: bqplot.ipynb
+```
+
+## Disable the `.ipynb` docs source binding
+
+By default, jupyterlite-sphinx binds the `.ipynb` source suffix so that it renders Notebooks included in the doctree with JupyterLite.
+This is known to bring warnings with plugins like sphinx-gallery, or to conflict with nbsphinx.
+
+You can disable this behavior by setting the following config:
+
+```python
+jupyterlite_bind_ipynb_suffix = False
+```

docs/full.md

@@ -0,0 +1,8 @@
+# Fullscreen access
+
+You can access the JupyterLite deployment that `jupyterlite-sphinx` made for you, in fullscreen, following the `./lite/lab` and `./lite/retro` relative urls:
+
+- [JupyterLab](./lite/lab/index.html)
+- [Retrolab](./lite/retro/index.html)
+
+If you want to open a specific notebook in fullscreen  JupyterLab/Retrolab you can use the `path` URL parameter, e.g. `./lite/lab/?path=my_noteboook.ipynb`.

docs/index.md

@@ -0,0 +1,44 @@
+# jupyterlite-sphinx
+
+A Sphinx extension that provides utilities for embedding JupyterLite in your docs.
+
+`jupyterlite-sphinx` brings the power of JupyterLite to your Sphinx documentation. It makes a full JupyterLite deployment in your docs and provide some utilities for using that deployment easily.
+
+```{eval-rst}
+.. replite::
+   :kernel: python
+   :toolbar: 0
+   :theme: JupyterLab Light
+   :width: 100%
+   :height: 600px
+
+   print("Hello from a JupyterLite console!")
+```
+
+```{toctree}
+:maxdepth: 2
+
+installation
+configuration
+```
+
+## Usage
+
+`jupyterlite-sphinx` provides a collection of directives that allows you to embed the different JupyterLite UIs directly in your documentation page.
+Each of those directives can be configured with the following options:
+
+- `width` (default `"100%"`) the width of the UI
+- `height` (default `"600px"`) the height of the UI
+- `theme` (default `None`) the JupyterLab theme to use
+- `prompt` (default `False`) whether or not to lazy-load the UI. If the value is a string, it will use this value for the prompt button.
+- `prompt_color` (default `#f7dc1e`) The color of the prompt button, if there is one.
+
+```{toctree}
+:maxdepth: 2
+
+directives/jupyterlite
+directives/retrolite
+directives/replite
+full
+changelog
+```

docs/installation.md

@@ -0,0 +1,19 @@
+# Installation
+
+You can install `jupyterlite-sphinx` with `pip`:
+
+```
+pip install jupyterlite-sphinx
+```
+
+then you need to add the `jupyterlite-sphinx` extension to your `conf.py` file of your sphinx docs:
+
+```python
+extensions = [
+    'jupyterlite_sphinx',
+    # And other sphinx extensions
+    # ...
+]
+```
+
+JupyterLite should automatically show up in your built online documentation. To preview it locally, you can navigate to the build directory (e.g. `_build/html`) and use `python -m http.server` to serve the site.