Documenting alternatives

[jayqi]

We should document alternative tools and provide some light discussion about differences.

Jupyter Notebook conversion / alternative formats

• nbconvert
• jupytext

Jupyter code review tools

• nbdime
• reviewnb

[mwouts]

Great idea! I'd be curious to see the comparison with Jupytext (which only does .py or .md exports, not .html, etc). Do you have an example of a sample review made with nbautoexport? I assume you review both the .ipynb and .py file, is that correct?

If you want to give a try at Jupytext, this local jupytext.toml (or .jupytext.toml) configuration file should have more or less the same effect as the one you describe in the README (put the file at the root of the project):

default_jupytext_formats = "notebooks///ipynb,notebooks/script///py:percent"

Click here for the corresponding pytest example

def test_nbautoexport_equivalent(tmpdir):
    cm = jupytext.TextFileContentsManager()
    cm.root_dir = str(tmpdir)

    nb_dir = tmpdir.mkdir('notebooks')
    script_dir = nb_dir.join('script')
    cfg_file = nb_dir.join(".jupytext.yml")

    nb_file = nb_dir.join("notebook.ipynb")
    py_file = script_dir.join("notebook.py")

    cfg_file.write("default_jupytext_formats: 'notebooks///ipynb,notebooks/script///py:percent'\n")

    cm.save(notebook_model(SAMPLE_NOTEBOOK), "notebooks/notebook.ipynb")
    assert nb_file.isfile()
    assert py_file.isfile()

Note that you can also use simpler configuration files like

default_jupytext_formats = "notebooks///ipynb,scripts///py:percent"

if you're OK with subfolders with the same parent, or even

default_jupytext_formats = "ipynb,py:percent"

if you're OK with having the text files in the same folder.