https://github.com/nthiery/rst-to-ipynb
Convert .rst to .ipynb
https://github.com/nthiery/rst-to-ipynb
Last synced: 29 days ago
JSON representation
Convert .rst to .ipynb
- Host: GitHub
- URL: https://github.com/nthiery/rst-to-ipynb
- Owner: nthiery
- License: bsd-3-clause
- Fork: true (stsievert/rst-to-ipynb)
- Created: 2015-09-22T22:25:19.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-10-04T17:39:02.000Z (about 2 years ago)
- Last Synced: 2025-09-29T12:08:56.429Z (3 months ago)
- Language: TeX
- Size: 2.02 MB
- Stars: 18
- Watchers: 2
- Forks: 17
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- License: LICENSE.txt
Awesome Lists containing this project
- -awesome-jupyter - rst2ipynb - Convert standalone reStructuredText files to Jupyter notebook file. (Rendering/Publishing/Conversion)
- awesome-jupyter - rst2ipynb - Convert standalone reStructuredText files to Jupyter notebook file. (Rendering/Publishing/Conversion)
README
rst2ipynb
=========
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. A better approach would be to implement
a proper Jupyter-export extension for Sphinx.
NEWS (2017-10): you may want to explore the recent https://github.com/QuantEcon/sphinxcontrib-jupyter/ that does just this.
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.
For [SageMath](http://sagemath.org) users: `rst2ipynb` is an optional package that you may install with:
sage -i rst2ipynb
then you can run it with:
sage -rst2ipynb ...
For [Cocalc](http://cocalc.org) users: `rst2ipynb` is already installed.
Usage
-----
To convert a reST file ``xxx.rst`` to a Jupyter notebook ``xxx.ipynb``, run::
rst2ipynb xxx.rst -o xxx.ipynb
Example
-------
- reST document: `all.rst `_
- Produced Jupyter notebook: `all.ipynb `_
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
See https://github.com/aaren/notedown/issues/33
Acknowledgements
----------------
rst2ipynb was partially funded by [OpenDreamKit](http://opendreamkit.org)