A reST to Jupyter notebook converter
Project description
This project provides a way to convert standalone reStructuredText files to Jupyter notebook files.
This is currently achieved by converting to markdown using pandoc and then to a Jupyter notebook using notedown, plus some configuration and tweaks.
Requirements
Python 3 (for proper UTF-8 support in notedown), pandoc, notedown
Installation
Install pandoc and then this module as usual:
git clone https://github.com/nthiery/rst-to-ipynb.git cd rst-to-ipynb pip3 install .
pip3 will install the other dependencies as needed.
Caveat: the notedown package on pipy (1.5.0, 2015-10-07) is somewhat outdated; for better conversion, it is recommended to install the latest version from the github repo.
Usage
To convert a reST file xxx.rst to a Jupyter notebook xxx.ipynb, run:
rst2ipynb xxx.rst -o xxx.ipynb
Example
TODO
[X] Handle Sage’s doctests
- [X] Fenced code blocks: fix incompatibility between pandoc output and notedown input.
Fixed in notedown; see: https://github.com/aaren/notedown/issues/29.
- [ ] Configurability of the default ReST role, in particular to handle maths in Sage’s ReST dialect.
Current status: hardcoded for Sage.
[ ] Configurability of custom ReST roles, in particular to handle Sage’s custom roles
- [ ] Proper argument parsing; escape characters, spaces, … are not
yet supported
- [ ] Handle input/output blocks within itemize and other indented constructions
