search

jupyter-book / jupyter-book

Create beautiful, publication-quality books and documents from computational content.
http://jupyterbook.org
BSD 3-Clause "New" or "Revised" License
3.88k stars 663 forks source link

Support for Org file? #796

Open kitaev-chen opened 4 years ago

kitaev-chen commented 4 years ago

Org(-mode) file is convenient under emacs, do you think is it a good point to support org file?

choldgraf commented 4 years ago

Hmm - I'm not sure what this is or how it would relate to Sphinx / the Jupyter Book build process. Could you give a bit more detail on how you'd imagine it being used in Jupyter Book?

kitaev-chen commented 4 years ago

Some people usually use org-mode in Emacs since org file have better block folding function and more powerful functionality, such as GTD, org-brain, org-roam, org-capture, etc.

The most benefit of org format is that it's easy to export 1 single org file to various format such as .md .html .pdf .tex. Jupyter-book support to render .ipynb .md .py(?) files, if it also support .org file, the Emacs community will definitely like this.

Of course another solution is from jupytext side, so that Emacs guys can write .org file and generate .ipynb file at the same time. So the jupyter-book can parse it.

choldgraf commented 4 years ago

How does org-mode work in the context of Sphinx though? That's what Jupyter Book is using under the hood. I doubt that we will include major changes to how the build process works, is there a way to make org mode function within the Sphinx ecosystem?

Rahuketu86 commented 4 years ago

It is possible to side load the org mode process to github actions. I take inspiration from https://fastpages.fast.ai/ project to offload parsing and conversion to native reader by wrapping them in a docker container and executing them through github action workflow step . I do org -> rst ( org mode docker) and then (rst -> book) using jupyter book build process.

My eventual plan is to write a specific backend inside org-mode specific to MyST Markdown format.

Here is the initial attempts results https://rahuketu86.github.io/orgbook/intro.html

github : https://github.com/rahuketu86/orgbook

I can use some guidance on sphinx build process. For something like specific build steps [ conversion --> metadata generation ---> html ] . I can use it to optimize the backend better.

I am also thinking of integrating pandoc for docx conversion in same way

fbob commented 4 years ago

+1 org-mode support should be seriously considered ... not only for jupyter-book but for all the jupyter ecosystem. They both share so much similarities. jupytext could be the link between them but sadly there is no org-mode support ... yet :)

choldgraf commented 4 years ago

I think what is needed to support org-mode is that somebody writes an org-mode parser for Sphinx / docutils. I don't know of one, but this would be a first-step towards getting it working in jupyter book.

Alternatively, it seems there are some org-mode tools that facilitate the use of the Sphinx ecosystem (e.g. https://github.com/msnoigrs/ox-rst).