Package: nbstencilaproxy
Jupyter + DAR/stencila = nbstencilaproxyJupyter+Darcompatibility exploration for runningStencilaonBinderDemoClick on the button below to launch an online Jupyter instance onmybinder.orgbased on this repository:Try it out!Open an the example Dar archive by clicking on "New > Stencila Session":AboutThis project is part of theeLife  Innovation Sprint 2018andMozilla Global Sprint 2018(seehttps://github.com/mozilla/global-sprint/issues/317)This project comprises two modules:a JavaScript package for installing and running Stencila (client/UI and services) in a Jupyter containera Python package (nbstencilaproxy) for installing and running a proxy (based onnbserverproxy) to access the UI as well as services provided by Stencila; the package also extends the Jupyter UI to add a "New Stencila Session" buttonTeam@minrk@nuestHow?Configuration of the imageSeveral configuration files in the directorybinder/are picked up by mybinder.org during the image build process and install the required software and several Stencila kernels.environment.ymlandrequirements.txtinstall Python dependenciesruntime.txtadds an R installationìnstall.Rinstalles and configures the R context for StencilapostBuildinstalls the notebook extensions forrunning a Stencila host and the Stencila user interface via a proxy (details below)extending the Jupyter UIenabling the Stencila Jupyter contextinstalls and configures the plain Python context for StencilaThe default archive is set inbinder/postBuildby configuring the environment variableSTENCILA_ARCHIVE.Running Stencila in the Jupyter containerWe first used Stencila's development build to run the app usingnode make -w -s -d /our/own/dir, but struggled a bit to configure the file storage, i.e. thedar-server, to use the directory we want to, and to run it in a full path configured by us instead ofmake.jsstarting thedar-serverrelative to__dirname.Eventuallywe ended up implementing our own minimal npm package that pulls in Stencila as a dependency and runs thedar-serverand static file server for the app using the files from thedistdirectory.
See the filestencila.jsfor details.
This gives us control of the paths and let's us get rid of complex development features (substance-bundleretc.).We also made our own version ofapp.js, getting rid of the virtual file storage stuff (vfs), defaulting storage tofs(file system), because that is what is needed for Jupyter - we do not need to host any examples.
In the same line, we built ownindex.html(based onexample.html) and serve that, which allows us to directly render a DAR document instead of a listing of examples and instruction and to use ourapp.js.Relevant path configurations comprise the local storage pathas well asthe URLs used by the client, accessing thedar-serverthrough thenbserverproxy.TheDockerfileinstalls our helper npm package and adds + configures thenbserverproxytool (seerequirements.txtandjupyter_notebook_config.py).Connecting Stencila to Jupyter kernelsStencila has "execution contexts" (the equivalent of Jupyter's "kernels") for R, Python, SQL, Javascript (in the browser), and Node.js. Execution contexts differ from kernels in a number of ways including local execution and dependency analysis of cells. Both of these are necessary for the reactive, functional execution model of Stencila Articles and Sheets.We could install these execution contexts in the Docker image. However, Stencila also has aJupyterContextwhich acts as a bridge between Stencila's API and Jupyter kernels. So, since the basejupyter/minimal-notebookimage already has a Jupyter kernel for Python installed it we decided to use that. This does mean however, that some of the reactive aspects of the Stencila UI won't work as expected. Also theJupyterContextis not well developed or tested.We have included thestencila-nodeNode.js package in the Docker image which provides theJupyterContextas well as aNodeContext(for executing Javascript) and aSqliteContext(for executing SQL) .Making Stencila available via a Proxynbstencilaproxyprovides Jupyter server and notebook extensions to proxy Stencila.
It is based onnbrsessionproxybut does not include the support nbrsessionproxy has for JupyterLab.InstallInstall package:pip install git+https://github.com/minrk/nbstencilaproxyInstall the extensions for all users on the system:jupyter serverextension enable  --py --sys-prefix nbstencilaproxy
jupyter nbextension     install --py --sys-prefix nbstencilaproxy
jupyter nbextension     enable  --py --sys-prefix nbstencilaproxyDevelopmentRun locally withrepo2docker# install repo2docker: https://repo2docker.readthedocs.io/en/latest/usage.html#running-repo2docker-locally# run repo2docker for the local repositoryjupyter-repo2docker--debug.Login by visiting the tokenized URL displayed e.g.http://localhost:8888/?token=99a7bc13...Click on the "New > Stencila Session" button on the Jupyter start page, opening thepy-jupyterexample, orOpen one of the included examples by appending the following parameters to the URL:Python (Jupyter Kernel):?archive=py-jupyterR:?archive=r-markdownMini (Stencila's own data analysis language):?archive=kitchen-sinkLicenseBSD 3-Clause License