diff --git a/README.md b/README.md index 91df534..7e0b305 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,55 @@ -# Python and R scripts as Jupyter notebooks +# Jupyter notebooks from/to Python or R scripts [![Pypi](https://img.shields.io/pypi/v/nbsrc.svg)](https://pypi.python.org/pypi/nbsrc) [![Pypi](https://img.shields.io/pypi/l/nbsrc.svg)](https://pypi.python.org/pypi/nbsrc) [![Build Status](https://travis-ci.com/mwouts/nbsrc.svg?branch=master)](https://travis-ci.com/mwouts/nbsrc) [![codecov.io](https://codecov.io/github/mwouts/nbsrc/coverage.svg?branch=master)](https://codecov.io/github/mwouts/nbsrc?branch=master) +![pylint Score](https://mperlet.github.io/pybadge/badges/9.6.svg) [![pyversions](https://img.shields.io/pypi/pyversions/nbsrc.svg)](https://pypi.python.org/pypi/nbsrc) +[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/mwouts/nbrmd/master?filepath=demo) -This package provides companion scripts (`.py` or `.R` extension) -to your Jupyter notebooks, that are always *synchronized* -with the notebook. With this you will be able to -- set the `.py` or `.R` script under version control -- modify the script outside of Jupyter, and easily merge multiple contributions -to the notebook using standard, text merge tools -- reload the latest version of the notebook from the `.py` or `.R` script. -Outputs for the cells with unchanged input are taken from the `.ipynb` file. +Jupyter notebooks are complex files, that contain source code, metadata, and +rich outputs. Here we offer a simple and complementary format for Jupyter +notebooks, as pure python (or R) companion scripts. + +The resulting python scripts are perfect candidates for +keeping notebooks under *version control*. They can be +*edited* outside of Jupyter, using +your favorite text editor, or even standard merge tools if you wish to merge +*multiple contributions* to a notebook. + +With the `nbsrc` package, any python or R script can be loaded as a notebook +in Jupyter. If a classical `ipynb` notebook with a matching name exists, +outputs for matching inputs are reconstructed. And, if you associate python +and jupyter files as recommended below, when a `ipynb` notebook opens, the +corresponding inputs are taken from the `py` file, which you may have updated +outside of Jupyter. + +## Can I have a demo? + +Sure. Try our package on [binder](https://mybinder.org/v2/gh/mwouts/nbrmd/master?filepath=demo)! + +There, you will be able +- to open and execute arbitrary python files as notebooks (give a try to +the matplotlib demo named `filled_step.py`, for instance) +- to open a notebook, then edit the companion python script, and reload the notebook, +to find up-to-date inputs in Jupyter. + +## How does the python version look like? + +Below is an example of a Jupyter notebook, together with its python representation. + +We have a battery of tests that ensure that +- Round trip conversion: python to notebook to python, is *identity* +- Round trip conversion, starting from a Jupyter notebook, preserve *source* +and *metadata*, not outputs. In some occasions (consecutive blank lines in +code cells), cells may be splitted into smaller ones. + +Python [notebook](https://mybinder.org/v2/gh/mwouts/nbrmd/master?filepath=tests/python_notebook_sample.py) in Jupyter | Python [script](https://github.com/mwouts/nbrmd/blob/master/tests/python_notebook_sample.py) +:--------------------------:|:-----------------------: +![](https://raw.githubusercontent.com/mwouts/nbsrc/master/img/python_notebook.png) | ![](https://raw.githubusercontent.com/mwouts/nbsrc/master/img/python_source.png) + +The representation of notebooks as R scripts follows the [standard](https://rmarkdown.rstudio.com/articles_report_from_r_script.html) for that language. ## How do I activate the companion script? @@ -24,7 +60,7 @@ c.NotebookApp.contents_manager_class = 'nbrmd.RmdFileContentsManager' c.ContentsManager.default_nbrmd_formats = 'ipynb,py' ``` -Then, make sure you have the `nbrmd` packages installed, and re-start jupyter, i.e. run +Then, make sure you have the `nbrmd` package up-to-date, and re-start jupyter, i.e. run ```bash pip install nbrmd --upgrade jupyter notebook @@ -56,25 +92,15 @@ In case you want both `.py` and `.Rmd`, please note that the order matters: the first non-`.ipynb` extension is the one used as the reference source for notebook inputs. -## Can I edit the python file? - -Yes, please! That's the precise purpose for the `nbsrc` package. When you're done, please _reload_ the notebook, i.e. refresh your notebook in the browser. Note that the url should have only the notebook name (no additional #), like -`http://localhost:8888/notebooks/GitHub/nbrmd/tests/python_notebook_sample.ipynb`. - -As mentioned above, reloading the `.ipynb` with actually load updated inputs from the python script. +## What is the difference between `nbsrc` and `nbrmd`? -It is not required to _restart_ the current kernel. Reloading may remove a few outputs (those corresponding to inputs you have changed), but it will preserve the python variables. - -Python notebook in Jupyter | Python script -:--------------------------:|:-----------------------: -![](https://raw.githubusercontent.com/mwouts/nbsrc/master/img/python_notebook.png) | ![](https://raw.githubusercontent.com/mwouts/nbsrc/master/img/python_source.png) +`nbrmd` is a python package that represents Jupyter notebooks as R markdown +files. It is also where notebooks as python scripts are implemented. But +I felt notebooks as scripts deserved a standalone documentation, and +that's the main reason for having the `nbsrc` package. - -## How do you represent notebooks as scripts? - -`.R` scripts follow the [standard](https://rmarkdown.rstudio.com/articles_report_from_r_script.html) for that language. - -Designing a comfortable standard for `.py` scripts is not trivial. The current format is documented [here](https://github.com/mwouts/nbrmd/blob/master/tests/python_notebook_sample.py). +You don't actually need the `nbsrc` package unless you want the command line +conversion tools. ## Command line conversion @@ -100,8 +126,3 @@ nbconvert jupyter.ipynb --to pynotebook nbconvert jupyter.ipynb --to rnotebook ``` -## And if I convert twice? - -Round trip conversion of scripts is identity. -Round trip conversion of Jupyter notebooks preserves the source, not outputs. -