Package: nbrmd
Jupyter notebooks as markdown documents, Python or R scriptsYou've always wanted to edit Jupyter notebooks in your favorite editor? To have Jupyter notebooks under version control? Or tocollaborateon Jupyter notebooks using standard (text-only) merge tools?Supported formatsThenbrmdpackage allows to open and edit, in Jupyter,Python and R scripts ( extensions.pyand.R)Markdown documents (extension.md)R Markdown documents (extension.Rmd).Obviously these documents can also be edited outside of Jupyter. You will find useful to refactor your notebook as a mere python script in a real IDE. If you are working on a documentation and you prefer the markdown format, you will be able to use both Jupyter and your specialized markdown editor.Reloading the updated document in Jupyter is just a matter of refreshing the browser. Refreshing preserves the python variables. Outputs are also preserved when you use the text notebooksin pairwith classical notebooks.Try our package on! Recommended experiments areHave a look at the sample text notebooks in thedemofolder. See how notebook are represented as textGo toand open these notebooksYou may also open arbitrary python scripts likematplotlib example.py(run it)Feel free to explore the package files with Jupyter (openREADME.mdat the project root)Check by yourself that outputs and variables are preserved, and inputs are updated, when the text notebook is modified outside of Jupyter (this isPaired Jupyter notebook and python script.ipynb).ScreenshotsRound-trip conversionRound trip conversion is safe! A few hundred of tests help to guarantee this.Script to Jupyter notebook, to script again is identity. If you
associate a Jupyter kernel to your notebook, that information will go to
a yaml header at the top of your script.Markdown to Jupyter notebook, to markdown again is identity.Jupyter to script, and Jupyter again preserves source and metadata.Jupyter to markdown, and Jupyter again preserves source and metadata (cell metadata available only for R markdown). Note that markdown cells with two consecutive blank lines will be splitted into multiple cells (as the two blank line pattern is used to separate cells).Jupyter setupTo open.py,.R,.mdand.Rmdfiles as notebooks in Jupyter, use ourContentsManager. That is:generate a jupyter config, if you don't have one yet, withjupyter notebook --generate-configedit the config and include the below:c.NotebookApp.contents_manager_class="nbrmd.RmdFileContentsManager"Then, make sure you have thenbrmdpackage up-to-date, and re-start jupyter, i.e. runpipinstallnbrmd--upgrade
jupyternotebookPaired notebooksIf you want to preserve inputs and outputs, while being able to edit the text format, then add annbrmd_formatsentry to the notebook metadata, in Jupyter, as follows:{
  "kernelspec": {
    "name": "python3",
    (...)
  },
  "language_info": {
    (...)
  },
  "nbrmd_formats": "ipynb,py"
}When you save the notebook, both the Jupyter notebook and the python scripts are updated. You can edit the text version
and then get the updated version in Jupyter by refreshing your browser (you may want to deactivate Jupyter's autosave with%autosave 0).Accepted formats are:ipynb,md,Rmd,pyandR. In case you want multiple text extensions, please note that the
order matters: the first non-ipynbextension
is the one used as the reference source for notebook inputs when you open theipynbfile.Finally, it is also possible to pair every notebook with a text representation. If you addc.NotebookApp.contents_manager_class = "nbrmd.RmdFileContentsManager"
c.ContentsManager.default_nbrmd_formats = "ipynb,py" # or "ipynb,nb.py" # or "ipynb,md" # or "ipynb,Rmd"to your Jupyter configuration file, theneveryJupyter notebook that you save will have a companion.py(.nb.py,.md, or.Rmd) notebook. And every.py(.nb.py,.md, or.Rmd) notebook will have a companion.ipynbnotebook.The default configuration can also contain multiple extension groups. Usec.NotebookApp.contents_manager_class="nbrmd.RmdFileContentsManager"c.ContentsManager.default_nbrmd_formats="ipynb,nb.py;py.ipynb,py"if you want.ipynbnotebooks to have.nb.pycompanion scripts, and.pyfiles to have.py.ipynbcompanion notebooks (learn more on the possible values fornbrmd_formatshere).Command line conversionThe package provides anbrmdscript for command line conversion between the various notebook extensions:nbrmdnotebook.ipynbmd--test# Test round trip conversionnbrmdnotebook.ipynbmd# display the markdown version on screennbrmdnotebook.ipynb.md# create a notebook.md filenbrmdnotebook.ipynb.py# create a notebook.py filenbrmdnotebook.ipynbnotebook.py# create a notebook.py filenbrmdnotebook.md.ipynb# overwrite notebook.ipynb (remove outputs)nbrmdnotebook.md.ipynb--update# update notebook.ipynb (preserve outputs)nbrmdnotebook1.mdnotebook2.py.ipynb# overwrite notebook1.ipynb notebook2.ipynbUsefull cell metadataSet"active": "ipynb,py"if you want that cell to be active only in the Jupyter notebook, and the Python script representation. Use"active": "ipynb"if you want that cell to be active only in Jupyter.Code cells that contain two consecutive blank lines use an explicit end-of-cell marker"endofcell"in the script representation.R markdown's cell optionsechoandincludeare mapped to the opposite of Jupyter cell metadatahide_inputandhide_output.Jupyter magicsJupyter magics are escaped in scripts and R markdown to allow code to be executed. Comment a magic with#noescapeon the same line to avoid escaping. User defined magics can be escaped with#escape. Magics are not escaped in the plain markdown representation.