Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/goerz/jupytext.nvim

Neovim plugin for editing Jupyter ipynb files via jupytext
https://github.com/goerz/jupytext.nvim

ipynb jupyter jupytext neovim neovim-plugin

Last synced: 21 days ago
JSON representation

Neovim plugin for editing Jupyter ipynb files via jupytext

Awesome Lists containing this project

README 

        
jupytext.nvim

=============



[![CI](https://github.com/goerz/jupytext.nvim/actions/workflows/ci.yml/badge.svg)](https://github.com/goerz/jupytext.nvim/actions/workflows/ci.yml)



The plugin enables editing [Jupyter notebook `.ipynb` files](https://jupyter.org) as plain text files by dynamically converting them through the [`jupytext` command line tool](https://github.com/mwouts/jupytext).



It is a rewrite of the [`jupytext.vim` plugin](https://github.com/goerz/jupytext.vim) for Neovim. Compared to the initial vimscript version of the plugin, it should behave more robustly and be more flexible. For example, it can auto-detect that language used in the notebook. Most importantly, though, it is designed to integrate well with setups that use [paired files](#paired-files).



Prerequisites

=============



The Python `juyptext` command line utility must be installed.



Use `:checkhealth jupytext`.



Installation

============



Load the plugin via your favorite package manager, and set it up so that `require("jupytext").setup(opts)` is called.



### Lazy.nvim



```lua

{

    'goerz/jupytext.nvim',

    opts = {},  -- see Options

}

```



Options

=======



The default options are:



```lua

opts = {

    format = "markdown",

    update = true,

    filetype = require("jupytext").get_filetype,

    sync_patterns = {"*.md", "*.py", "*.jl"},

    autosync = true,

}

```



#### `format`



The plain text format to use.



#### `update`



Whether or not to use the `--update` flag to `jupytext`. This

preserves the output in the edited `.ipynb` file. Without this, every save

clears all outputs from the underlying file.



#### `filetype`



A string, or function `get_filetype(path, format, metadata)` that

returns a string. The `filetype` that will be set for the buffer after loading

the file, and thus determines syntax highlighting and other settings. The

`get_filetype` function receives the absolute path to the `.ipynb` file, the

value of the `--format` flag to `jupytext`, and a Lua table with the metadata

from the `.ipynb` file. The default function will set the `filetype` to

`"markdown"` for markdown formats, and to `metadata.kernelspec.language` (the

language indicated in the notebook's metadata) otherwise.



#### `sync_pattern`



Specifications of autogroup patterns for plain text files. If

`autosync=true` (see [`autosync`](#autosync)), this sets up autocommands for all files matching the given

pattern, so that if there is the file also exists in the same folder with a

`.ipynb` extension, `jupyter --sync` is called before loading the file and

after saving the file. Furthermore the `:checktime` function will be called

periodically in the background to react to a running Jupyter instance updating

the file in the background.



#### `autosync`



If true, enable automatic synchronization for files paired via the Jupytext

plugin for Jupyter Notebook and Jupyter Lab



Usage

=====



When opening an `.ipynb` file, this plugin will inject itself into the loading process and convert the `json` data in the file to a plain text format by piping it through `jupytext` using with the `format` set in [Options](#options).



Paired Files

============



The Jupytext project provides the command line utility `jupytext`, which this plugin uses to convert to and from the native `json` data in a `.ipynb` file. However, its original and primary purpose is to provide a plugin for the Jupyter Lab and Notebook server that allows it to pair `.ipynb` files with one or more plain text formats.



Somewhat confusingly, the original vimscript version of this plugin did not work particularly well in the context of paired notebook files.



This version of the plugin has full support for paired notebook files, as long as the `autosync` option is set to `true` (see [Options](#options)).



Without the `autosync` option, editing a paired `.ipynb` file will unpair it.



Development

===========



While developing locally `make` can be used apply the Lua code style, generate the documentation, and run the tests. See `make help` for details.



All of these are verified via GitHub Actions when pushing the repository.



### Documentation



The documentation for the plugin is maintained in this `README` file.This must be translated to the vim help format in `doc/jupytext.txt`, which can be done by running `make doc` locally, or directly the `./.panvimdoc/panvimdoc.sh` script. It uses [`pandoc`](https://pandoc.org) to convert markdown to vim help text via the custom filter in `./.panvimdoc/scripts/panvimdoc.lua`. The filter has been adapted from [`kdheepak/panvimdoc`](https://github.com/kdheepak/panvimdoc), see [its documentation](https://raw.githubusercontent.com/kdheepak/panvimdoc/refs/heads/main/doc/panvimdoc.md) for details on the recommended markdown syntax to use, or just follow the style used in the document.



The `doc/jupytext.txt` must be updated every time this `README.md` file is updated. GitHub Actions will check that the two files are in sync, but it will not update the vim-help file automatically.



History

=======



### v.0.1.0-dev (unreleased)



* Initial release after complete rewrite from `jupytext.vim`

* Avoid the use of temporary files that might clash with paired scripts

* Added support obtaining the notebook language from its metadata, enabling use of the "script" format

* Added support of automatic synchronization with paired files.