Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify improvements / differences from nbconvert #107

Closed
choldgraf opened this issue Oct 18, 2018 · 8 comments
Closed

Clarify improvements / differences from nbconvert #107

choldgraf opened this issue Oct 18, 2018 · 8 comments
Labels
question Further information is requested

Comments

@choldgraf
Copy link
Contributor

This looks like a really interesting project! One question I've been trying to figure out is "how is this different from nbconvert?" It seems like they have partially overlapping functionality, so I'm curious how you see these two projects differentiating one another.

@mwouts
Copy link
Owner

mwouts commented Oct 18, 2018

Hello @choldgraf , thanks for asking!

As you state, jupytext and nbconvert can both export Jupyter notebooks to markdown and scripts. The added value of jupytext versus nbconvert is the support for the reverse conversion: with jupytext, you can convert a notebook to a script, edit the script, and then update the original jupyter notebook.

There are two ways you can use jupytext:

  • on the command line. Use the --update flag to preserve output cells for unchanged input cells.
  • as a plugin for Jupyter Notebook or Jupyter Lab. See how we pair a text representation to a Jupyter notebook in the demo, edit the text representation, and get the updated notebook in Jupyter

A few more comments:

@choldgraf
Copy link
Contributor Author

@mwouts very cool - thanks for the explanation :-)

A couple quick questions:

  • How lightweight is this compared with nbconvert? At sphinx-gallery we automatically generate notebooks from the .py files that are there. We're currently doing this with custom code because we want to avoid too many heavy dependencies (and nbconvert can be heavy).
  • To that point, have you considered separating out the "converting text formats from one to the other" code from the "running a paired server" code? I think one of the challenges of maintaining/growing nbconvert was that it tries to do a lot which makes it hard for others to contribute and understand the codebase.
  • I looked through the Sphinx Gallery code and the formatting isn't quite right (Sphinx Gallery python files need to begin with an rST-formatted docstring). If you point me in the right direction perhaps I can give a patch!

@mwouts
Copy link
Owner

mwouts commented Oct 18, 2018

Thanks @choldgraf for the feedback! Let me try to answer your questions...

How lightweight is this compared with nbconvert?

I am not sure! Jupytext has very few dependencies. And its code is about 3k lines. Do you quantify that as light?

To that point, have you considered separating out the "converting text formats from one to the other" code from the "running a paired server" code?

Well, Jupytext only focuses on reading/writing notebooks. The contents manager (i.e. the plugin for Jupyter) is just one file (389 lines). There is no server within Jupytext.

I looked through the Sphinx Gallery code and the formatting isn't quite right (Sphinx Gallery python files need to begin with an rST-formatted docstring).

I see! You're right. The first markdown cell should be exported as a docstring. To achieve this, we would just need to add a cell metadata 'cell_marker' equal to """ for the first markdown cell of the notebook, in that function. But I am afraid the YAML header is not very Sphinx Gallery compliant... Do you see a way to have some content in the sphinx file that is ignored by Sphinx Gallery?

@mwouts mwouts added the question Further information is requested label Oct 18, 2018
@mwouts
Copy link
Owner

mwouts commented Oct 18, 2018

@choldgraf , on the branch 0.8.4 the first markdown cell is now exported as a docstring. Is this better? Please also let me know if you see how to mark the YAML header so that Sphinx will ignore it.

@mwouts
Copy link
Owner

mwouts commented Oct 24, 2018

A few improvements, including the doctring for the first cell, are available in a pre-release version:

pip install jupytext==v0.8.4rc0

The YAML header will not be created if an option is set on Jupytext's content manager, cf. the documentation.

@choldgraf , I will close this issue as I think we've answered your questions here. Please let me know if you have other questions!

@mwouts mwouts closed this as completed Oct 24, 2018
@choldgraf
Copy link
Contributor Author

hey - just saw that I hadn't responded before, my bad! re: the YAML header, I don't think there's any way to get sphinx to ignore it unfortunately, so it'd have to be done with some kind of post-processing if it isn't possible to control with jupytext :-/ I'll take a stab at using this when I have a moment and maybe can make some PRs!

@mwouts
Copy link
Owner

mwouts commented Oct 25, 2018

Sure, I will be glad to receive your pull request, they are welcome!

In the 0.8.4 release candidate Jupytext does have the option to not generate the YAML header (this is documented on the README). Still I am sure you will find room for more improvements... Let me know!

@choldgraf
Copy link
Contributor Author

It seems like you're one step ahead of me here 😊

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
question Further information is requested
Projects
None yet
Development

No branches or pull requests

2 participants