{
    "info": {
        "author": "Min RK, Daniel N\u00fcst, Ryan Lovett",
        "author_email": "",
        "bugtrack_url": null,
        "classifiers": [
            "Framework :: Jupyter"
        ],
        "description": "# Jupyter + DAR/stencila = nbstencilaproxy\n\n[Jupyter](https://jupyter.org/) + [Dar](https://github.com/substance/dar) compatibility exploration for running [Stencila](http://stenci.la/) on [Binder](https://mybinder.org/)\n\n## Demo\n\nClick on the button below to launch an online Jupyter instance on [mybinder.org](https://mybinder.org) based on this repository:\n\nTry it out! [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/minrk/nbstencilaproxy/master?urlpath=stencila)\n\nOpen an the example Dar archive by clicking on \"New > Stencila Session\":\n\n![](new-session-button.png)\n\n## About\n\nThis project is part of the [eLife  Innovation Sprint 2018](https://elifesci.org/innovationsprint2018) and [Mozilla Global Sprint 2018](https://mozilla.github.io/global-sprint/) (see [https://github.com/mozilla/global-sprint/issues/317](https://github.com/mozilla/global-sprint/issues/317))\n\nThis project comprises two modules:\n\n- a JavaScript package for installing and running Stencila (client/UI and services) in a Jupyter container\n- a Python package (nbstencilaproxy) for installing and running a proxy (based on [`nbserverproxy`](https://github.com/jupyterhub/nbserverproxy)) to access the UI as well as services provided by Stencila; the package also extends the Jupyter UI to add a \"New Stencila Session\" button\n\n## Team\n\n- [@minrk](https://github.com/minrk)\n- [@nuest](https://github.com/nuest)\n\n## How?\n\n### Configuration of the image\n\nSeveral configuration files in the directory `binder/` are picked up by mybinder.org during the image build process and install the required software and several Stencila kernels.\n\n- `environment.yml` and `requirements.txt` install Python dependencies\n- `runtime.txt` adds an R installation\n- `\u00ecnstall.R` installes and configures the R context for Stencila\n- `postBuild`\n  - installs the notebook extensions for\n    - running a Stencila host and the Stencila user interface via a proxy (details below)\n    - extending the Jupyter UI\n    - enabling the Stencila Jupyter context\n  - installs and configures the plain Python context for Stencila\n\nThe default archive is set in `binder/postBuild` by configuring the environment variable `STENCILA_ARCHIVE`.\n\n### Running Stencila in the Jupyter container\n\nWe first used Stencila's development build to run the app using `node make -w -s -d /our/own/dir`, but struggled a bit to configure the file storage, i.e. the `dar-server`, to use the directory we want to, and to run it in a full path configured by us instead of `make.js` starting the `dar-server` relative to `__dirname`.\n_Eventually_ we ended up implementing our own minimal npm package that pulls in Stencila as a dependency and runs the `dar-server` and static file server for the app using the files from the `dist` directory.\nSee the file `stencila.js` for details.\nThis gives us control of the paths and let's us get rid of complex development features (`substance-bundler` etc.).\n\nWe also made our own version of `app.js`, getting rid of the virtual file storage stuff (`vfs`), defaulting storage to `fs` (file system), because that is what is needed for Jupyter - we do not need to host any examples.\nIn the same line, we built own `index.html` (based on `example.html`) and serve that, which allows us to directly render a DAR document instead of a listing of examples and instruction and to use our `app.js`.\n\nRelevant path configurations comprise the local storage path _as well as_ the URLs used by the client, accessing the `dar-server` through the `nbserverproxy`.\n\nThe `Dockerfile` installs our helper npm package and adds + configures the `nbserverproxy` tool (see `requirements.txt` and `jupyter_notebook_config.py`).\n\n### Connecting Stencila to Jupyter kernels\n\nStencila 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.\n\nWe could install these execution contexts in the Docker image. However, Stencila also has a `JupyterContext` which acts as a bridge between Stencila's API and Jupyter kernels. So, since the base `jupyter/minimal-notebook` image 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 the `JupyterContext` is not well developed or tested.\n\nWe have included the [`stencila-node`](https://www.npmjs.com/package/stencila-node) Node.js package in the Docker image which provides the `JupyterContext` as well as a `NodeContext` (for executing Javascript) and a `SqliteContext` (for executing SQL) .\n\n### Making Stencila available via a Proxy\n\n**nbstencilaproxy** provides Jupyter server and notebook extensions to proxy Stencila.\nIt is based on [**nbrsessionproxy**](https://github.com/jupyterhub/nbrsessionproxy) but does not include the support nbrsessionproxy has for JupyterLab.\n\n**Install**\n\nInstall package:\n\n```\npip install git+https://github.com/minrk/nbstencilaproxy\n```\n\nInstall the extensions for all users on the system:\n\n```\njupyter serverextension enable  --py --sys-prefix nbstencilaproxy\njupyter nbextension     install --py --sys-prefix nbstencilaproxy\njupyter nbextension     enable  --py --sys-prefix nbstencilaproxy\n```\n\n## Development\n\n- Run locally with `repo2docker`\n\n```bash\n# install repo2docker: https://repo2docker.readthedocs.io/en/latest/usage.html#running-repo2docker-locally\n\n# run repo2docker for the local repository\njupyter-repo2docker --debug .\n```\n\n- Login by visiting the tokenized URL displayed e.g. `http://localhost:8888/?token=99a7bc13...`\n\n- Click on the \"New > Stencila Session\" button on the Jupyter start page, opening the `py-jupyter` example, or\n\n- Open one of the included examples by appending the following parameters to the URL:\n  - Python (Jupyter Kernel): `?archive=py-jupyter`\n  - R: `?archive=r-markdown`\n  - Mini ([Stencila's own data analysis language](https://github.com/stencila/mini)): `?archive=kitchen-sink`\n\n## License\n\nBSD 3-Clause License",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/minrk/nbstencilaproxy",
        "keywords": "Jupyter",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "nbstencilaproxy",
        "package_url": "https://pypi.org/project/nbstencilaproxy/",
        "platform": "",
        "project_url": "https://pypi.org/project/nbstencilaproxy/",
        "project_urls": {
            "Homepage": "https://github.com/minrk/nbstencilaproxy"
        },
        "release_url": "https://pypi.org/project/nbstencilaproxy/0.1.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Jupyter extension to proxy Stencila",
        "version": "0.1.1"
    },
    "last_serial": 4087468,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "b2b7efac308a7bcfa213bddbed71a230",
                    "sha256": "10d4fbdaa6dfba493728de49dae1f63da15f5c0c28ba58f81f266adcf84492aa"
                },
                "downloads": -1,
                "filename": "nbstencilaproxy-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "b2b7efac308a7bcfa213bddbed71a230",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 292216,
                "upload_time": "2018-07-20T23:26:53",
                "url": "https://files.pythonhosted.org/packages/50/0c/cc374bd1113e0a23ac5e26108777cd2302bfc6ab7d81589980098ccab140/nbstencilaproxy-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e1369a08c6a86cb5dc34cf78c343a8fe",
                    "sha256": "9511e7eb1c8b820737db681858355029ff37b043574319447d63e14a08988bc0"
                },
                "downloads": -1,
                "filename": "nbstencilaproxy-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "e1369a08c6a86cb5dc34cf78c343a8fe",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 296148,
                "upload_time": "2018-07-20T23:51:20",
                "url": "https://files.pythonhosted.org/packages/2b/88/7370fbd6517f481ff96e007e482c89739d2c798fab04a258c2fceca96aca/nbstencilaproxy-0.1.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "e1369a08c6a86cb5dc34cf78c343a8fe",
                "sha256": "9511e7eb1c8b820737db681858355029ff37b043574319447d63e14a08988bc0"
            },
            "downloads": -1,
            "filename": "nbstencilaproxy-0.1.1.tar.gz",
            "has_sig": false,
            "md5_digest": "e1369a08c6a86cb5dc34cf78c343a8fe",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 296148,
            "upload_time": "2018-07-20T23:51:20",
            "url": "https://files.pythonhosted.org/packages/2b/88/7370fbd6517f481ff96e007e482c89739d2c798fab04a258c2fceca96aca/nbstencilaproxy-0.1.1.tar.gz"
        }
    ]
}