{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Custom Notebook Formats\n",
    "\n",
    "By default, Jupyter notebooks are stored in files with the suffix `.ipynb`,\n",
    "which use the JSON format for storage.\n",
    "\n",
    "However, there are libraries available which allow storing notebooks in different formats,\n",
    "using different file suffixes.\n",
    "\n",
    "To use a custom format in `nbsphinx`, you can specify the\n",
    "`nbsphinx_custom_formats` option in your `conf.py` file.\n",
    "You have to provide the file extension\n",
    "and a conversion function that takes the contents of a file (as a string)\n",
    "and returns a Jupyter notebook object.\n",
    "\n",
    "```python\n",
    "nbsphinx_custom_formats = {\n",
    "    '.mysuffix': 'mylibrary.converter_function',\n",
    "}\n",
    "```\n",
    "\n",
    "The converter function can be given as a string or as a function object.\n",
    "\n",
    "One example for such library is [jupytext](https://github.com/mwouts/jupytext),\n",
    "which allows storing the contents of Jupyter notebooks in \n",
    "Markdown and R-Markdown, as well as plain Julia, Python and R files.\n",
    "\n",
    "Since its conversion function takes more than a single string argument,\n",
    "just using the function name `'jupytext.reads'` will not work.\n",
    "We have to create a function object,\n",
    "and one way to do that is using a `lambda` function like this:\n",
    "\n",
    "```python\n",
    "import jupytext\n",
    "\n",
    "nbsphinx_custom_formats = {\n",
    "    '.Rmd': lambda s: jupytext.reads(s, '.Rmd'),\n",
    "}\n",
    "```\n",
    "\n",
    "You can of course use multiple formats by specifying multiple conversion functions."
   ]
  }
 ],
 "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}