Add a getting started notebook for jupytext (and Binder) #257
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| { | ||
| "cells": [ | ||
| { | ||
| "cell_type": "markdown", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "# Getting started with Jupytext\n", | ||
| "\n", | ||
| "This small notebook shows you how to activate Jupytext in the JupyterLab\n", | ||
| "environment. We'll show you a few things that you can do with Jupytext and\n", | ||
| "a bit of what happens under the hood.\n", | ||
| "\n", | ||
| "**Note: to run this notebook locally, you need to first follow the Jupytext\n", | ||
| "installation instructions and activate the JupyterLab plugin. If you're on\n", | ||
| "Binder, it should already work.**\n", | ||
| "\n", | ||
| "## Enabling Jupytext in a new notebook\n", | ||
| "\n", | ||
| "This notebook is brand new - it hasn't had any special extra metadata added\n", | ||
| "to it. \n", | ||
| "\n", | ||
| "If we want Jupytext to save files in multiple formats automatically,\n", | ||
| "we can use the JupyterLab **command palette** to do so.\n", | ||
| "\n", | ||
| "* Click on the little 🎨 icon to the left\n", | ||
| "* Then type **`Jupytext`**. You should see a number of commands come up. Each\n", | ||
| " one tells Jupytext to save the notebook in a different\n", | ||
| " file format automatically.\n", | ||
| "* Select **Pair notebook with Markdown**\n", | ||
| "\n", | ||
| "That's it! If you have Jupytext installed, it will now save your notebook in\n", | ||
| "markdown format automatically when you save this `.ipynb` file.\n", | ||
| "\n", | ||
|
There was a problem hiding this comment. I would add something like 'in addition'. It is important to make it clear that Jupyter will continue to save the original notebook as well! Also, maybe we can mention that the two files really point to the same document, and that the Markdown file can be edited as well. |
||
| "After you've done this, save the notebook. You should now see a new file called\n", | ||
| "**`get_started.md`** in the same directory as this notebook.\n", | ||
| "\n", | ||
| "## How does Jupytext know to do this?\n", | ||
| "\n", | ||
| "Jupytext uses notebook-level metadata to keep track of what languages are paired\n", | ||
| "with a notebook. Below we'll print the metadata of this notebook so you can see\n", | ||
| "what the Jupytext metadata looks like." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "import nbformat as nbf\n", | ||
| "from IPython.display import JSON\n", | ||
| "notebook = nbf.read('./get_started.ipynb', nbf.NO_CONVERT)\n", | ||
| "JSON(notebook['metadata'])" | ||
| ] | ||
|
There was a problem hiding this comment. Chris, one meta-question... would you mind if we stored this notebook in its Markdown representation in the There was a problem hiding this comment. ooh that's a cool idea - yeah sounds good There was a problem hiding this comment. More explicitly: I was thinking of adding these lines to |
||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "As you select different languages from the command palette (following the instructions\n", | ||
| "above) and save the notebook, you'll see this metadata change." | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "## That's it!\n", | ||
| "\n", | ||
| "Play around with different kinds of code and outputs to see how each is\n", | ||
| "converted into its corresponding text format. Here's a little Python code\n", | ||
| "to get you started:" | ||
| ] | ||
| }, | ||
| { | ||
| "cell_type": "code", | ||
| "execution_count": null, | ||
| "metadata": {}, | ||
| "outputs": [], | ||
| "source": [ | ||
| "import numpy as np\n", | ||
| "import matplotlib.pyplot as plt\n", | ||
| "\n", | ||
| "plt.scatter(*np.random.randn(2, 100), c=np.random.randn(100), s=np.random.rand(100)*100)" | ||
| ] | ||
|
There was a problem hiding this comment. This makes me think that we do not have an explicit mention that Jupytext works with every kind of notebook, even the most interactive notebooks with widgets, etc... Maybe we could write a FAQ section in the help and include typical questions like that one. |
||
| }, | ||
| { | ||
| "cell_type": "markdown", | ||
| "metadata": {}, | ||
| "source": [ | ||
| "# Experiment with other notebooks\n", | ||
| "\n", | ||
| "There are several other demo notebooks for you to explore Jupytext's functionality,\n", | ||
| "try them out!" | ||
| ] | ||
| } | ||
| ], | ||
| "metadata": { | ||
| "kernelspec": { | ||
| "display_name": "Python 3", | ||
| "language": "python", | ||
| "name": "python3" | ||
| }, | ||
| "language_info": { | ||
| "codemirror_mode": { | ||
| "name": "ipython", | ||
| "version": 3 | ||
| }, | ||
| "file_extension": ".py", | ||
| "mimetype": "text/x-python", | ||
| "name": "python", | ||
| "nbconvert_exporter": "python", | ||
| "pygments_lexer": "ipython3", | ||
| "version": "3.6.5" | ||
| } | ||
| }, | ||
| "nbformat": 4, | ||
| "nbformat_minor": 2 | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's correct. If we don't include that line, then we get asked if the jupytext extension for jupyterlab should be built, so it's better to do that in advance