57 lines
2 KiB
Markdown
57 lines
2 KiB
Markdown
|
# IpynbDiff: Better diff for Jupyter Notebooks
|
||
|
|
|
||
|
|
This is a simple diff tool that cleans up Jupyter notebooks, transforming each [notebook](example/1/from.ipynb)
|
||
|
|
into a [readable markdown file](example/1/from_html.md), keeping the output of cells, and running the
|
||
|
|
diff after. Markdowns are generated using an opinionated Jupyter to Markdown conversion. This means
|
||
|
|
that the entire file is readable on the diff.
|
||
|
|
|
||
|
|
The result are diffs that are much easier to read:
|
||
|
|
|
||
|
|
| Diff | IpynbDiff |
|
||
|
|
| ----------------------------------- | ----------------------------------------------------- |
|
||
|
|
| [Diff text](example/diff.txt) | [IpynbDiff text](example/ipynbdiff_percent.txt) |
|
||
|
|
|  |  |
|
||
|
|
|
||
|
|
This started as a port of [ipynbdiff](https://gitlab.com/gitlab-org/incubation-engineering/mlops/poc/ipynbdiff),
|
||
|
|
but now has extended functionality although not working as git driver.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
### Generating diffs
|
||
|
|
|
||
|
|
```ruby
|
||
|
|
IpynbDiff.diff(from_path, to_path, options)
|
||
|
|
```
|
||
|
|
|
||
|
|
Options:
|
||
|
|
|
||
|
|
```ruby
|
||
|
|
@default_transform_options = {
|
||
|
|
preprocess_input: true, # Whether the input should be transformed
|
||
|
|
write_output_to: nil, # Pass a path to save the output to a file
|
||
|
|
format: :text, # These are the formats Diffy accepts https://github.com/samg/diffy
|
||
|
|
sources_are_files: false, # Weather to use the from/to as string or path to a file
|
||
|
|
raise_if_invalid_notebook: false, # Raises an error if the notebooks are invalid, otherwise returns nil
|
||
|
|
transform_options: @default_transform_options, # See below for transform options
|
||
|
|
diff_opts: {
|
||
|
|
include_diff_info: false # These are passed to Diffy https://github.com/samg/diffy
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Transforming the notebooks
|
||
|
|
|
||
|
|
It might be necessary to have the transformed files in addition to the diff.
|
||
|
|
|
||
|
|
```ruby
|
||
|
|
IpynbDiff.transform(notebook, options)
|
||
|
|
```
|
||
|
|
|
||
|
|
Options:
|
||
|
|
|
||
|
|
```ruby
|
||
|
|
@default_transform_options = {
|
||
|
|
include_frontmatter: false, # Whether to include or not the notebook metadata (kernel, language, etc)
|
||
|
|
}
|
||
|
|
```
|