"What is Jupyter" explainer document #728
Conversation
ericsnekbytes
changed the title
ericsnekbytes
changed the title
| "Jupyter" can mean a lot of things, so let's start from the beginning, and | ||
| break it down: |
There was a problem hiding this comment.
| "Jupyter" can mean a lot of things, so let's start from the beginning, and | |
| break it down: | |
| "Jupyter" can mean a lot of things. Here are a few ways that we use it: |
"break it down" is idiomatic English, which may not be understood by a global audience. Let's be more direct.
| "Jupyter" can mean a lot of things, so let's start from the beginning, and | ||
| break it down: | ||
|
|
||
| First and foremost, "Project Jupyter" is a large umbrella project that covers |
There was a problem hiding this comment.
| First and foremost, "Project Jupyter" is a large umbrella project that covers | |
| "Project Jupyter" is a large umbrella project that covers |
Avoids a cliché expression, which especially at the very beginning of a long doc, is not needed
|
|
||
| First and foremost, "Project Jupyter" is a large umbrella project that covers | ||
| many different software offerings and tools. That includes "Jupyter Notebook" | ||
| and "JupyterLab", which are both popular notebook-editor programs. **The** |
There was a problem hiding this comment.
Should we start by explaining what a Jupyter notebook (small N) is? It seems odd to talk about Jupyter Notebook (big N), the program, before we talk about the notebooks that it can edit.
| products or ideas, which can cause confusion. Let's take a look at each piece, | ||
| and provide some clarity, below. | ||
|
|
||
| # What is a "Computational Notebook" anyway? |
There was a problem hiding this comment.
| # What is a "Computational Notebook" anyway? | |
| # What is a computational notebook? |
"Computational Notebook" is not a proper noun. I rarely see the term "computational" used — should we just use "notebook" (in lowercase) here?
| A famous computer programmer (Donald Knuth) popularized the idea to combine | ||
| explanatory plain english text with computer code, which is commonly called |
There was a problem hiding this comment.
| A famous computer programmer (Donald Knuth) popularized the idea to combine | |
| explanatory plain english text with computer code, which is commonly called | |
| Donald Knuth popularized the idea of combining | |
| explanatory plain English text with computer code, which is commonly called |
Mr. Knuth needs no introduction 😄
| The project is split into largely independent subprojects which handle | ||
| different aspects of Jupyter software and the community. A central council, | ||
| the Jupyter Executive Council (LINK), makes decisions about project-wide | ||
| goals and policies, while different subprojects handle the actual development | ||
| of the various software components. |
There was a problem hiding this comment.
This may be too much detail for an introduction. Might be best to link to the governance docs, or perhaps to delete this entirely.
| The two most popular notebook editor programs are Jupyter-Notebook and | ||
| JupyterLab, though there are others. Which one you choose to use is |
There was a problem hiding this comment.
Rather than describing these as "the two most popular notebook editors", we might want to instead characterize them as two notebook editors published by Project Jupyter. There are many other editors produced and published by 3rd-party commercial vendors, including my own employer, and which may be popular. We can't endorse any of them in this document, but I am concerned that this phrasing seems to minimize the outside developer community for notebook editors.
|
|
||
| ### Notebook Editor Programs | ||
|
|
||
| - [JupyterLab](https://jupyterlab.readthedocs.io/en/latest/) |
There was a problem hiding this comment.
Is it too much to characterize JupyterLab as an IDE in this section?
| ### The notebook format | ||
|
|
||
| - [nbformat.readthedocs.io](https://nbformat.readthedocs.io) | ||
|
|
||
| Jupyter uses the .ipynb format to store your notebook files (where the data | ||
| and outputs of your notebook reside for long term storage). The .ipynb format | ||
| is interpreted and modified by the nbformat software library. | ||
|
|
||
| TODO: features, more info, basic exmaplanation of how it works/structure |
There was a problem hiding this comment.
Not sure if this is necessary in a basic introduction.
| ### JupyterHub | ||
|
|
||
| - [jupyterhub.readthedocs.io](https://jupyterhub.readthedocs.io) | ||
|
|
||
| JupyterHub provides a multi-user management system where many different people | ||
| can log in and use their own isolated notebook editor program and environment. | ||
|
|
||
| With JupyterHub, editing and running notebook files is still performed by an | ||
| editor program like Lab or Notebook. The Hub is responsible for authenticating | ||
| users and providing them their corresponding Lab/Notebook instance connection. | ||
|
|
||
| Jupyter-Hub can be set up in different system configurations: | ||
|
|
||
| - In a single computer | ||
| - In a cluster of computers | ||
| - In containers in the cloud | ||
|
|
||
| JupyterHub is quite flexible for many different multi-user scenarios. | ||
|
|
||
| ### IPython | ||
|
|
||
| - [IPython]([ipython.readthedocs.io/interactive/tutorial]: https://ipython.readthedocs.io/en/stable/interactive/tutorial.html) | ||
|
|
||
| A long time ago, a precursor to Jupyter was created, called ipython (see | ||
| the [History of Jupyter][] to learn more about that). It provided some of | ||
| the same fast, advanced REPL features that Jupyter still has today, and it | ||
| is the default Python kernel bundled with JupyterLab and Notebook. Some of | ||
| the features ipython provides: | ||
|
|
||
| - Foobar | ||
| - Bizbaz | ||
| - WikRakRum | ||
| - interactive shell: [ipython.readthedocs.io/interactive/tutorial][] | ||
| - magic commands: [ipython.readthedocs.io/interactive/magics][] | ||
|
|
||
| For more details on IPython features check [`docs.jupyter.org > Projects > IPython`](https://docs.jupyter.org/en/latest/projects/ipython_projects.html). | ||
|
|
||
|
|
||
|
|
||
| ### Interactive Buttons, Sliders and more with ipywidgets | ||
|
|
||
| - [Jupyter Widgets (AKA ipywidgets)](https://ipywidgets.readthedocs.io/en/latest/) | ||
|
|
||
| Jupyter Widgets (also called ipywidgets) provides interactive interface | ||
| elements that you can add directly into your notebooks. | ||
|
|
||
| - Note: The subproject and high-level references to the widgets were renamed to | ||
| Jupyter-Widgets, but Jupyter-Widgets and IPyWidgets are the very same thing. To | ||
| not break compatibility with older code, the software library is still called | ||
| `ipywidgets`. |
There was a problem hiding this comment.
These may be a bit too detailed for a basic introduction.
I feel like, for a user just getting started with Jupyter, they should learn first about the notebook concept and 1 or maybe 2 apps (Notebook and Lab). Additional documentation can shed light on other projects.
The Jupyter Docs Working Group is drafting this "What is Jupyter" document as part of a larger effort to improve documentation quality across all subprojects, and to better inform and educate the community about the Jupyter ecosystem.
This document is supposed to explain the foundations of everything we work on inside the Jupyter ecosystem, basic concepts that are essential to our work, but may not be fully understood or separated out by users, like:
I can use your help fleshing out the examples, providing cool samples that illustrate the awesome things you can do with Jupyter, to get people excited as part of their first steps into the Jupyter universe.
This document is being actively edited by members of the Docs Working Group.