📚 DOCS: Add example of using other kernels

Author: chrisjsewell

.circleci/config.yml

@@ -13,6 +13,7 @@ jobs:
             - cache-pip
 
       - run: |
+          pip install --user "ipython<=7.11.0"
           pip install --user .[rtd]
 
       - save_cache:

.readthedocs.yml

@@ -7,6 +7,7 @@ python:
         path: .
         extra_requirements:
           - rtd
+      - requirements: docs/requirements.txt
 
 sphinx:
   builder: html

docs/conf.py

@@ -59,6 +59,7 @@
     "repository_branch": "master",
     "use_edit_page_button": True,
     "path_to_docs": "docs/",
+    "expand_sections": ["use/index", "examples/index"],
 }
 
 intersphinx_mapping = {
@@ -85,3 +86,11 @@
 myst_amsmath_enable = True
 myst_html_img_enable = True
 myst_url_schemes = ("http", "https", "mailto")
+
+
+def setup(app):
+    import subprocess
+
+    # this is required to register the coconut kernel with Jupyter,
+    # to execute docs/examples/coconut-lang.md
+    subprocess.check_call(["coconut", "--jupyter"])

docs/examples/coconut-lang.md

@@ -11,24 +11,34 @@ kernelspec:
   name: coconut
 ---
 
-# Notebooks in other languages
+# Other Programming Languages
 
-<http://coconut-lang.org/>
+A Jupyter Notebook can utilise any program kernel that implements the [Jupyter messaging protocol](http://jupyter-client.readthedocs.io/en/latest/messaging.html) for executing code.
+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 other languages](https://github.com/jupyter/jupyter/wiki/Jupyter-kernels).
+
+In this notebook we demonstrate executing code with the [Coconut Programming Language](http://coconut-lang.org), a variant of Python built for *simple, elegant, Pythonic functional programming*.
+
+In the first example we will define a recursive `factorial` function, a fundamentally functional approach that doesn’t involve any state changes or loops:
 
 ```{code-cell} coconut
 def factorial(n):
     """Compute n! where n is an integer >= 0."""
-    if n `isinstance` int and n >= 0:
-        acc = 1
-        for x in range(1, n+1):
-            acc *= x
-        return acc
+    case n:
+        match 0:
+            return 1
+        match x is int if x > 0:
+            return x * factorial(x-1)
     else:
         raise TypeError("the argument to factorial must be an integer >= 0")
 
 3 |> factorial |> print
 ```
 
+Although this example is very basic, pattern-matching is both one of Coconut’s most powerful and most complicated features.
+
+In the second example, we implement the quick sort algorithm.
+This quick_sort algorithm works using a bunch of new constructs:
+
 ```{code-cell} coconut
 def quick_sort(l):
     """Sort the input iterator using the quick sort algorithm."""
@@ -42,6 +52,8 @@ def quick_sort(l):
 [3,0,4,2,1] |> quick_sort |> list |> print
 ```
 
+Finally, we see that exceptions are raised as one would expect:
+
 ```{code-cell} coconut
 :tags: [raises-exception]
 x

docs/index.md

@@ -64,6 +64,7 @@ For information on using and configuring MyST-NB, as well as some examples of no
 outputs, see the pages below:
 
 ```{toctree}
+:maxdepth: 2
 use/index
 use/markdown
 ```
@@ -72,6 +73,7 @@ In addition, here is a reference page that uses the `jupyter-sphinx` package to
 outputs, to compare how these outputs look relative to the MyST-NB style.
 
 ```{toctree}
+:maxdepth: 2
 examples/index
 ```
 

docs/requirements.txt

@@ -0,0 +1,2 @@
+# this is only required by coconut kernel
+ipython<=7.11.0

tox.ini

@@ -24,6 +24,8 @@ commands = pytest {posargs}
 [testenv:docs]
 recreate = false
 extras = rtd
+deps =
+    ipython<=7.11.0  # required by coconut
 whitelist_externals = rm
 commands =
     rm -rf docs/_build