Metadata-Version: 2.1
Name: nbrmd
Version: 0.1.1
Summary: Jupyter from/to R markdown notebooks
Home-page: https://github.com/mwouts/nbrmd
Author: Marc Wouts
Author-email: marc.wouts@gmail.com
License: MIT
Description: # From Jupyter notebooks to R markdown, and back
        
        [![Pypi](https://img.shields.io/pypi/v/nbrmd.svg)](https://pypi.python.org/pypi/nbrmd)
        [![Pypi](https://img.shields.io/pypi/l/nbrmd.svg)](https://pypi.python.org/pypi/nbrmd)
        [![Build Status](https://travis-ci.com/mwouts/nbrmd.svg?branch=master)](https://travis-ci.com/mwouts/nbrmd)
        [![codecov.io](https://codecov.io/github/mwouts/nbrmd/coverage.svg?branch=master)](https://codecov.io/github/mwouts/nbrmd?branch=master)
        [![pyversions](https://img.shields.io/pypi/pyversions/nbrmd.svg)](https://pypi.python.org/pypi/nbrmd)
        
        
        This is a converter that creates Jupyter notebooks from R markdown notebooks, and the opposite.
        
        You will be interested in this if
        - you prefer a simple markdown format over Jupyter's json notebook (especially you want to only version the input of your notebooks, and be able to merge easily different versions of the notebooks).
        - you want to use RStudio's advanced rendering of notebooks (like: chunk options for activating/deactivating code or input, choosing figure size, etc), or even the well documented [slide format](https://rmarkdown.rstudio.com/ioslides_presentation_format.html)
        - or, you have a collection of R notebooks and you want to open them in Jupyter
        
        ## What is R markdown?
        
        As the name states, R markdown (extension `.Rmd`) was designed in the R community. It is the format used by the RStudio IDE for notebooks. It actually support [many languages](https://yihui.name/knitr/demo/engines/). A few months back, the support for python significantly improved with the arrival of the [`reticulate`](https://github.com/rstudio/reticulate) package.
        
        R markdown is almost identical to markdown export of Jupyter notebooks. For reference, Jupyter notebooks are exported to markdown using either
        - _Download as Markdown (.md)_ in Jupyter's interface,
        - or `nbconvert notebook.ipynb --to markdown`.
        
        First difference is that code chunks can be evaluated. While markdown's standard syntax for a python code paragraph is
        
            ```python
            1+1
            ```
            
        R markdown will also have code chunks like
        
            ```{python}
            1+1
            ```
        
        with this syntax meaning that the code above should be _evaluated_.
        
        Second difference is the common presence of a YAML header, that describes the notebook title, author, and desired output (HTML, slides, PDF...).
        
        Look at [nbrmd/tests/ioslides.Rmd](https://github.com/mwouts/nbrmd/blob/master/tests/ioslides.Rmd) for a sample R markdown file (that, actually, only includes python cells).
        
        ## How do I use the converter?
        
        Install the package with
        ```python
        pip install nbrmd
        ```
          
        This provides a `nbrmd` script that converts Jupyter notebooks to R markdown notebooks, and vice-versa.
        
        Use it as:
        ```bash
        nbrmd jupyter.ipynb      # this prints the Rmarkdown alternative
        nbrmd jupyter.ipynb -i   # this creates a jupyter.Rmd file
        nbrmd jupyter.Rmd   -i   # and this, a jupyter.ipynb file
        ```
        
        ## And if I convert twice?
        
        Double conversion of R markdown is identity.  
        Double conversion of Jupyter notebooks preserves the source, but metadata and outputs are lost, like in most [pre-commit hooks](https://gist.github.com/minrk/6176788).
        
        ## Can I save my Jupyter notebook under this format?
        
        The `nbrmd` package offers a `pre_save_hook` for Jupyter notebook server, that will, in addition to your Jupyter notebook, maintain an up-to-date R markdown version. To use it,
        - generate a jupyter config, if you don't have one yet, with `jupyter notebook --generate-config`
        - edit the config and include this:
        ```python
        from nbrmd import pre_save_hook
        c.ContentsManager.pre_save_hook = pre_save_hook
        ```    
        
        Please note that, however, if you edit the `.Rmd` file, the `.ipynb` will not be updated, unless you re-generate it with:
        ```bash
        nbrmd notebook.Rmd
        ```
        
        
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Topic :: Text Processing :: Markup
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.6
Description-Content-Type: text/markdown
