📘 Desktop, Jupyter Extension, libraries, and more
Switch branches/tags
Clone or download
captainsafia Merge pull request #3442 from rsnk96/cleanup
Fix inconsistent names for functions and actions/types
Latest commit 6346d2c Oct 16, 2018
Permalink
Failed to load latest commit information.
.circleci set jest to only use one worker on circleCI Oct 9, 2018
.github Declare as stale after 300 days Sep 18, 2018
applications Merge pull request #3442 from rsnk96/cleanup Oct 17, 2018
doc/design edit per review Aug 2, 2018
flow-typed Fix flow errors and use fixmes if flow def is incomplete Oct 3, 2018
initiatives httpsify some urls (#3139) Jul 29, 2018
packages Merge pull request #3442 from rsnk96/cleanup Oct 17, 2018
scripts fix typo in our test shim script (#3386) Oct 1, 2018
styleguide semi-automate deployment of style guide May 31, 2018
.eslintignore Remove unused vars from applications Oct 11, 2018
.eslintrc Convert a few eslint rules to warnings so they can be fixed in anothe… Oct 13, 2018
.flowconfig ignore jupyter extension build artifacts Aug 9, 2018
.gitattributes chore: normalize line endings Dec 11, 2016
.gitignore Send kernel shutdown messages when closing windows. Oct 9, 2018
.npmignore Use yarn Apr 30, 2017
.npmrc explicitly set the registry to npmjs Aug 7, 2018
.prettierignore Reorganize applications and packages (#2149) Dec 14, 2017
.prettierrc create a prettierrc Mar 29, 2018
.travis.yml remove example notebooks from desktop packaging Aug 29, 2018
CHANGELOG.md noting jext support for Python < 3.6 Sep 10, 2018
CODE_OF_CONDUCT.md Update CODE_OF_CONDUCT.md Sep 4, 2018
CONTRIBUTING.md Update references to NPM in Contributing Document Oct 10, 2018
LICENSE fix attribution clause Dec 16, 2017
README.md Replace scoped package building command with yarn native command Oct 11, 2018
RELEASING.md update the release guidance Aug 6, 2018
USER_GUIDE.md Added menu items and shortcuts for cell actions Oct 9, 2018
appveyor.yml remove app build from appveyor Jan 2, 2018
azure-pipelines.yml Set up CI with Azure Pipelines Sep 24, 2018
babel.config.js Remove unused vars from applications Oct 11, 2018
codecov.yml Disable codecov being required to pass Oct 5, 2017
lerna.json lerna version in lerna.json is no longer necessary Sep 7, 2018
nbformat.v4.json stick in nbformat v4 schema for local use Jun 6, 2018
package.json Update dependency eslint-plugin-flowtype to v3 Oct 13, 2018
renovate.json remove lockfile maintenance Aug 7, 2018
styleguide.config.js Add styleguidist setup for Media components Oct 15, 2018
yarn.lock Update dependency eslint-plugin-flowtype to v3 Oct 13, 2018

README.md

nteract nteract animated logo

codecov.io slack in lerna Circle CI Status Shield

|| BasicsUsers || ContributorsDevelopmentMaintainers || SponsorsMade possible by ||

Basics

nteract is first and foremost a dynamic tool to give you flexibility when writing code, exploring data, and authoring text to share insights about the data.

Edit code, write prose, and visualize.

We support Jupyter kernels locally on your system and on remote JupyterHubs via Binder.

Users

Installing the nteract desktop application

If you're here to install the nteract desktop app, visit nteract.io to download a binary and install or visit the releases page.

Installing nteract web

Our current flavor of nteract web runs on top of the jupyter server. Install it with pip:

pip install nteract_on_jupyter

Now, run jupyter nteract and you're running nteract on jupyter!

Try the nteract playground

We're still hard at work on the playground. Here's a sneak peek to explore: https://play.nteract.io

User Guide

For the user guide, please check USER_GUIDE.md


Contributors

The contributors are listed in the contributors page on GitHub.

To learn how to contribute to nteract, head on over to our contributing guide.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to rgbkrk@gmail.com.

Feel free to post issues on GitHub or chat with us in Slack (request an invite) if you need help or have questions. If you have trouble creating an account on Slack, either email rgbkrk@gmail.com or post an issue on GitHub.

Development

Overview of nteract's monorepo

This repository is a monorepo, which basically means that the repository hosts more than one module or application. In our case, we have two main directories:

packages/ -- components used as an individual library
applications/ -- all the user facing applications (i.e. desktop, play)

The packages directory has the components needed to build new applications, and the applications has the desktop app, the play app, and a few more.

Why have a monorepo? The monorepo contains many components and packages that can be mixed and remixed to create new applications. The monorepo keeps these elements together so they are easy to discover and use. Another benefit is that the monorepo makes it easy to iterate on applications that share common components. For example, if we update a component, such as the Jupyter message handling, and happen to introduce an issue when making a change to the desktop app and happened to break it for use by play.nteract.io web app we would notice the issue in tandem.

Getting Started

To get started developing, set up the nteract monorepo.

Set the monorepo up in dev mode

Requires Node.js and yarn.

  1. Fork this repo
  2. Clone your fork or this repo git clone https://github.com/nteract/nteract
  3. cd to the directory where you cloned it
  4. yarn install

To keep up-to-date with changes to the root nteract/nteract branch:

  1. Set the root as a remote: git remote add upstream https://github.com/nteract/nteract.git

When changes are made to the root nteract/nteract, they can then be pulled from the root and merged to your master branch:

  1. git pull upstream master
  2. yarn clean
  3. yarn install

Windows Caveats

When building nteract on a Windows machine, you'll need to have vcbuild installed for node-gyp to be able to build the ZMQ bindings required by the Jupyter spec. If you do not have it installed, you may do so by running the following from a Windows PowerShell launched as an Adminstrator:

npm install -g --production windows-build-tools

Additionally, you'll need to install GTK 2 for node-canvas. Follow step 2 of this instruction set to do this.

Building a specific package

In some cases you'll want to modify an individual base package (i.e. commutable or transforms) and not rebuild all of the other packages. To target a build of a specific package, use this command, replacing packageName with the fully qualified name of the package you want to hack on:

yarn build:only packageName

For example, to hack on the transforms package, use

yarn build:only @nteract/transforms

Hacking on the Desktop application

Quick and dirty (manual)

yarn app:desktop

As you make changes, you will have to close the entire app (CMD-q on macOS or CNTL-c at the terminal) and then run yarn app:desktop again to see the changes.

Progressive Webpack build (automatic)

In separate terminals run:

yarn build:desktop:watch

and

yarn spawn

This progressive webpack build will keep rebuilding as you modify the source code. When you open a new notebook, you'll get the fresh, up-to-date copy of the notebook app.

Logging

console.log statements in the main Electron process are piped to stdout. console.log statements in the Electron renderer process go to the regular Dev Tools console (accessible from the View menu). Set ELECTRON_ENABLE_LOGGING=1 to pipe renderer console.log to the launching terminal as well. This is useful for debugging crashes and notebook closing behaviors.

Hacking on play

Run:

yarn app:play

Then open 127.0.0.1:3000 in your browser. You'll be able to make changes to play and see the changes update live.

If you make changes to any packages/ while hacking on play, you'll want to rebuild those using the instructions for building specific packages.

Troubleshooting

I upgraded my developer installation and things are broken!

  • Try yarn clean && yarn

I want to debug redux actions and state changes.

  • Enable redux-logger by spawning the application with yarn spawn:debug.

I keep getting a pop-up asking: Do you want the application "nteract Helper.app" to accept incoming network connections? while developing or using a custom build of nteract on macOS.

  • This is how the the macOS firewall behaves for unsigned apps. On a signed app, the dialog won't show up again after approving it the first time. If you're using a custom build of nteract, run:

    sudo codesign --force --deep --sign - /Applications/nteract.app
    

    You will have to do this again every time you rebuild the app.


Maintainers

Creating a release

Individual packages

Allow lerna to publish all of packages/*

$ lerna publish
... follow prompts to publish any packages, choosing the appropriate semver

Desktop application

Follow instructions in Releasing the Desktop application.


Sponsors

Work on the nteract notebook is currently sponsored by

NumFocus

We're on a common mission to build a great notebook experience. Feel free to get in touch if you'd like to help. Resources go towards paying for additional work by seasoned designers and engineers.

Made possible by

The nteract project was made possible with the support of

Netflix OSS

If your employer allows you to work on nteract during the day and would like recognition, feel free to add them to this "Made possible by" list.

|| BasicsUsers || ContributorsDevelopmentMaintainers || SponsorsMade possible by ||