Add a getting started notebook for jupytext (and Binder) #257

choldgraf · 2019-06-19T22:07:51Z

This adds an extra notebook to the demo notebooks, updates the Binder postBuild files to activate the lab and notebook extensions, and updates the Binder link to point to this new notebook.

Here's what the link will look like when people click it now:

https://mybinder.org/v2/gh/choldgraf/jupytext/binder_env?urlpath=lab/tree/demo/get_started.ipynb

(note, the link above points to my fork so it'll build, but the PR link points to the right repo)
What do you think? :-)

codecov · 2019-06-19T22:11:27Z

Codecov Report

Merging #257 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #257   +/-   ##
=======================================
  Coverage   99.16%   99.16%           
=======================================
  Files          66       66           
  Lines        6491     6491           
=======================================
  Hits         6437     6437           
  Misses         54       54

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 513b7a6...c0ff979. Read the comment docs.

mwouts · 2019-06-19T23:00:34Z

Thanks @choldgraf . Yes sure a step by step demo is a great idea! And even maybe, we could cleanup the demo folder and just keep 1. this getting started notebook, and 2. the other World population notebook (which role is to demo all the available formats).

mwouts · 2019-06-19T23:10:13Z

binder/postBuild

@@ -3,3 +3,8 @@ python -m bash_kernel.install

 # Trust our notebook
 jupyter trust demo/World\ population.ipynb
+
+# Set up extensions for JupyterLab and Notebook
+jupyter labextension install jupyterlab-jupytext


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

mwouts · 2019-06-19T23:11:11Z

binder/postBuild

+# Set up extensions for JupyterLab and Notebook
+jupyter labextension install jupyterlab-jupytext
+jupyter nbextension install --py jupytext --user
+jupyter nbextension enable --py jupytext --user


I think these two lines are not needed: the notebook extension is already available in the current binder

mwouts · 2019-06-19T23:14:51Z

demo/get_started.ipynb

+    "\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",


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.

mwouts · 2019-06-19T23:16:28Z

demo/get_started.ipynb

+    "from IPython.display import JSON\n",
+    "notebook = nbf.read('./get_started.ipynb', nbf.NO_CONVERT)\n",
+    "JSON(notebook['metadata'])"
+   ]


Nice example! Thanks

Chris, one meta-question... would you mind if we stored this notebook in its Markdown representation in the demo folder, and generate the ipynb in the postBuild with Jupytext? This way we would'nt need to review an ipynb file any more 😄

ooh that's a cool idea - yeah sounds good

More explicitly: I was thinking of adding these lines to postBuild:

cd demo jupytext get_started.md --to ipynb --update-metadata '{"jupytext":null}' rm get_started.md

mwouts · 2019-06-19T23:21:45Z

demo/get_started.ipynb

+    "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)"
+   ]


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.

choldgraf · 2019-06-20T15:56:56Z

ok - latest push does the following things:

Removes most of the demo files (all but the World population.ipynb one)
Adds a "getting started" file in markdown
Adds a bit to the postBuild script that will create a notebook from this, then remove the md file in the Binder
Addresses some miscellaneous stuff you mentioned above

What do you think?

mwouts · 2019-06-20T16:34:40Z

Excellent! Thank you so much @choldgraf . I have only three remarks left:

I'd prefer to keep all the text representations of the World Population notebook (sorry I was not clear), because it is even easier to go to the demo folder on GitHub and have a look at them rather than starting binder. And we have links to these text representations in the doc - see also Links to sample md files do not work in read the docs #255
I think you can remove the Paired Jupyter notebook and python script completely. So, in .gitignore we should just see get_started.ipynb
In the notebook, you use the word language to describe the text representation of the notebook. Maybe I would have rather used format. What do you think?

choldgraf · 2019-06-20T19:11:04Z

good points - ok I think I addressed all of the above. I also fixed #255 by a hacky solution, which is to add an anchor to the link. Apparently readthedocs will automatically strip out the .md if you're using the markdown parser, but if you make it mylink.org/myfile.md#some-header then that will prevent it from being stripped.

mwouts · 2019-06-20T19:42:38Z

Well done! Thank you again @choldgraf

choldgraf added 3 commits June 19, 2019 13:58

updating binder environment and link

bae4714

adding binder demo

f100eb5

adding binder links

0764de9

choldgraf force-pushed the binder_env branch from 1b238ce to 0764de9 Compare June 19, 2019 22:11

mwouts reviewed Jun 19, 2019

View reviewed changes

choldgraf force-pushed the binder_env branch from ee5cd21 to 090ac77 Compare June 20, 2019 00:49

removing extra demo files and keeping markdown

9e34354

choldgraf force-pushed the binder_env branch from 090ac77 to 9e34354 Compare June 20, 2019 00:50

mwouts mentioned this pull request Jun 20, 2019

Can we avoid "jupyterlab-jupytext needs to be included in build" ? #259

Closed

mwouts added this to the 1.1.7 milestone Jun 20, 2019

choldgraf mentioned this pull request Jun 20, 2019

Links to sample md files do not work in read the docs #255

Closed

adding back in world population and small edits

c0ff979

mwouts merged commit af70905 into mwouts:master Jun 20, 2019

mwouts mentioned this pull request Jun 23, 2019

1.1.7 #261

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a getting started notebook for jupytext (and Binder) #257

Add a getting started notebook for jupytext (and Binder) #257

choldgraf commented Jun 19, 2019 •

edited

Loading

codecov bot commented Jun 19, 2019 •

edited

Loading

mwouts commented Jun 19, 2019

mwouts Jun 19, 2019

mwouts Jun 19, 2019

mwouts Jun 19, 2019

mwouts Jun 19, 2019

mwouts Jun 19, 2019

choldgraf Jun 19, 2019

mwouts Jun 19, 2019

mwouts Jun 19, 2019

choldgraf commented Jun 20, 2019

mwouts commented Jun 20, 2019

choldgraf commented Jun 20, 2019

mwouts commented Jun 20, 2019

Add a getting started notebook for jupytext (and Binder) #257

Add a getting started notebook for jupytext (and Binder) #257

Conversation

choldgraf commented Jun 19, 2019 • edited Loading

codecov bot commented Jun 19, 2019 • edited Loading

Codecov Report

mwouts commented Jun 19, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Jun 20, 2019

mwouts commented Jun 20, 2019

choldgraf commented Jun 20, 2019

mwouts commented Jun 20, 2019

choldgraf commented Jun 19, 2019 •

edited

Loading

codecov bot commented Jun 19, 2019 •

edited

Loading