-
Notifications
You must be signed in to change notification settings - Fork 0
/
jupytext.txt
304 lines (221 loc) · 13.1 KB
/
jupytext.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
*jupytext.txt* Edit .ipynb files
==============================================================================
Table of Contents *jupytext-table-of-contents*
1. jupytext.nvim |jupytext-jupytext.nvim|
2. Prerequisites |jupytext-prerequisites|
3. Installation |jupytext-installation|
4. Options |jupytext-options|
5. Usage |jupytext-usage|
6. Paired Files |jupytext-paired-files|
7. Compatibility |jupytext-compatibility|
8. History |jupytext-history|
==============================================================================
1. jupytext.nvim *jupytext-jupytext.nvim*
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 for Neovim of the `jupytext.vim` plugin
<https://github.com/goerz/jupytext.vim>. See |jupytext-history| for changes
relative to the original vimscript version.
==============================================================================
2. Prerequisites *jupytext-prerequisites*
The `jupytext` command line utility <https://github.com/mwouts/jupytext> must
be installed.
After following the |jupytext-installation| instructions, the `:checkhealth
jupytext` command can be used inside Neovim to verify the prerequisites.
==============================================================================
3. Installation *jupytext-installation*
Load the plugin via your favorite package manager. `Lazy.nvim`
<https://lazy.folke.io> is recommended.
Lazy.nvim ~
Use the following plugin specification:
>lua
{
'goerz/jupytext.nvim',
version = '0.2.0',
opts = {}, -- see Options
}
<
Manual setup ~
If you are not using a package manager, copy the `lua/jupytext.lua` file into
your runtime folder (e.g., `~/.config/nvim/`). Then, in your `init.lua` file,
call `require("jupytext").setup(opts)` where `opts` is a table that may
contain any of the keys listed in |jupytext-options|.
==============================================================================
4. Options *jupytext-options*
The default options are:
>lua
opts = {
jupytext = 'jupytext',
format = "markdown",
update = true,
filetype = require("jupytext").get_filetype,
new_template = require("jupytext").default_new_template(),
sync_patterns = { '*.md', '*.py', '*.jl', '*.R', '*.Rmd', '*.qmd' },
autosync = true,
handle_url_schemes = true,
}
<
`jupytext` *jupytext-jupytext*
The `jupytext` command to use. If `jupytext` is not on your `PATH`, you could
set an absolute path here. Can also be set via a `b:jupytext_jupytext`
variable.
`format` *jupytext-format*
The plain text format to use. See the description of `OUTPUT_FORMAT` in
`jupytext --help`: `'markdown'` or `'script'`, or a file extension: `'md'`,
`'Rmd'`, `'jl'`, `'py'`, `'R'`, …, `'auto'` (script extension matching the
notebook language), or a combination of an extension and a format name, e.g.,
`'md:myst'`, `'md:markdown'`, `'md:pandoc'`, or `'py:percent'`, `'py:light'`,
`'py:sphinx'`, `'py:hydrogen'`.
Using `format='ipynb'` loads and writes the file in the original `json`
format.
The `format` option may also be given as a function that calculates the
`format` from two arguments:
- `path`: the absolute path to the `.ipynb` file being loaded
- `metadata`: a table with metadata information from the original JSON data in
the `.ipynb` file. Of particular interest may be the field
`metadata.jupytext.formats` if one wanted to implement something where
paired notebooks would preferentially use the paired format instead of a
common default value.
To set the `format` option temporarily on a per-buffer basis, set
`b:jupytext_format` and reload the file.
`update` *jupytext-update*
Whether or not to use the `--update` flag to `jupytext`. If `true`
(recommended), this preserves existing outputs in the edited `.ipynb` file. If
`false`, every save clears all outputs from the underlying file.
This can be temporarily overridden with a `b:jupytext_update` variable.
`filetype` *jupytext-filetype*
The buffer `filetype` setting to use after loading the file, which determines
syntax highlighting, etc. Can be given as a string, or more commonly as a
function that returns a string after receiving three arguments:
- `path`: the absolute path to the `.ipynb` file being loaded
- `format`: the value of the `format` option
- `metadata`: a table with metadata information from the original JSON data in
the `.ipynb` file. This should contain, e.g., the notebook language in
`metadata.kernelspec.language`
The default function used for this setting uses `"markdown"` for markdown
formats, and the value of `metadata.kernelspec.language` otherwise. Like the
previous options, `b:jupytext_filetype` is available to temporarily override
the choice of filetype.
`new_template` *jupytext-new_template*
When editing a new (non-existing) `.ipynb` file, a `template.ipynb` file to
load into the buffer. The default built-in template is for a Python notebook.
While it is possible to manually edit the YAML header to change the kernel
and/or language, if you primarily work with non-Python notebooks, it might be
useful to set a custom template.
`sync_pattern` *jupytext-sync_pattern*
Patterns for plain text files that should be recognized as "syncable". If
`autosync=true` (see below), and if, for a file matching the patterns, there
also exists a file with an `.ipynb` extension, autocommands will be set up for
`jupyter --sync` to be called before loading the file and after saving the
file. This also periodically calls the `:checktime` function in the background
to determine whether the file has changed on disk (by a running Jupyter
server, presumably), and reloads it when appropriate.
Note that the `sync_pattern` only determines for which plain text files the
appropriate autocommands will be set up in Neovim. The setting is independent
of which Jupytext pairings are active, which is in the metadata for the
`.ipynb` files. All linked files will automatically be kept in sync. Likewise,
when editing `.ipynb` files directly, _all_ linked files will be kept in sync
automatically if `autosync=true`, irrespective of `sync_pattern`.
`autosync` *jupytext-autosync*
If `true` (recommended), enable automatic synchronization for files paired via
the Jupytext plugin (the plugin for Jupyter Lab). For `.ipynb` files, this
checks if the notebook is paired to any plain text files. If so, it will call
`jupytext --sync` before loading the file and after saving it, to ensure all
files are being kept in sync. It will also periodically check whether the
`.ipynb` file has changed on disk and reload it if necessary, setting the
|`autoread`| option for the current buffer.
`handle_url_schemes` *jupytext-handle_url_schemes*
If `true`, set up |`BufReadPost`|, |`BufWritePre`|, and |`BufWritePost`|
handlers for buffers with a URL scheme name (like
`oil-ssh://hostname/path/to/file.ipynb`). This converts the buffer content
from and to the `ipynb` representation under the assumption that some other
plugin is responsible for reading and writing the buffer. See
|jupytext-compatibility| for details.
==============================================================================
5. Usage *jupytext-usage*
When opening an `.ipynb` file, this plugin will inject itself into the loading
process (on |`BufReadCmd`|) and convert the `json` data in the file to a plain
text format by piping it through `jupytext` using the `format` set in
|jupytext-options|.
On saving (on |`BufWriteCmd`|), the original `.ipynb` file will be updated by
piping the content of the current buffer back into `jupytext`. With the
default `update` setting, this will keep existing outputs and metadata in the
notebook. When saving the buffer to a new file, it will be converted if the
filename has an `.ipynb` extension. Otherwise, the buffer will be written
unchanged.
Files that have a URL scheme in their name are converted in a less efficient
manner based on their buffer content, if `handle_url_schemes = true`. See
|jupytext-compatibility| for details.
==============================================================================
6. Paired Files *jupytext-paired-files*
While the Jupytext project provides the command line utility `jupytext` used
by this plugin for on-the-fly conversion between `.ipynb` and plain text
formats, its _primary_ purpose is to provide a plugin for Jupyter to _pair_
`.ipynb` files with one or more text files that are easier to manage in
version control.
The intent of the original `jupytext.vim` plugin was to edit `.ipynb` files
_not_ paired in such a way, and not loaded in an active Jupyter session. With
this rewritten version of the plugin, `jupytext.nvim` now supports editing
`.ipynb` files with Neovim if they are paired in Jupyter, and, at least in
principle, even while the notebooks are actively loaded in a running Jupyter
server. For this to work, the `autosync` option must be set to `true`
(default, see |jupytext-options|). This automatically handles the update of
any paired files and watches for modifications of the file on disk while it is
being edited. Saving a paired file while `autosync = false` will unpair it.
==============================================================================
7. Compatibility *jupytext-compatibility*
The `jupytext.nvim` plugin has some compatibility with other plugins that read
and write files via a URL scheme. For example:
- vim-fugitive <https://github.com/tpope/vim-fugitive> uses `fugitive://` URL
schemes internally. With `handle_url_schemes = true` in |jupytext-options|,
it should be possible to, e.g., use `:Gvdiffsplit` and stage changes for an
`.ipynb` file using a plain text representation.
- oil.nvim <https://github.com/stevearc/oil.nvim> uses an `oil-ssh://` URL
scheme for editing files over SSH
<https://github.com/stevearc/oil.nvim?tab=readme-ov-file#ssh>. The
`jupytext.nvim` plugin should be able to translate the buffer to and from
plain text transparently.
This relies on the plugins’ implementation of `BufReadCmd` and `BufWriteCmd`
handlers that explicitly trigger `BufReadPost`, `BufWritePre` and
`BufWritePost` autocommands, as the above plugins do.
For local `.ipynb` files where `jupytext.nvim` handles `BufReadCmd` and
`BufWriteCmd`, it will likewise trigger `BufReadPost`, `BufWritePre` and
`BufWritePost` autocommands. This allows for further customization and
potential integration with other plugins.
In general, compatibility with other plugins should be considered
experimental.
The `jupytext.nvim` plugin is not compatible with `gitsigns.nvim`
<https://github.com/lewis6991/gitsigns.nvim>. It is best to deactivate
`gitsigns` for `.ipynb` files via the `on_attach` callback in that plugin’s
`opts` (see `:help gitsigns-config-on_attach`):
>lua
require('gitsigns').setup{
…
on_attach = function(bufnr)
if vim.api.nvim_buf_get_name(bufnr):match('%.ipynb$') then
-- Do not attach for .ipynb file, since these are converted
-- with jupytext.nvim
return false
end
end,
}
<
==============================================================================
8. History *jupytext-history*
v0.2.0 (2024-12-28) ~
- Added: ability to create new `.ipynb` files. These are created from a
template file that can be configured via the `new_template` option.
- Added: ability to translate buffer content for files with URL schemes
(`handle_url_schemes` option). This enables, e.g., compatibility with
vim-fugitive <https://github.com/tpope/vim-fugitive>.
v0.1.0 (2024-12-18) ~
Initial release; Rewrite of `jupytext.vim`
<https://github.com/goerz/jupytext.vim>. The new plugin targets Neovim and has
been rewritten in Lua to avoid restrictions of the old plugin:
- Avoid the use of temporary files in the same folder as the `.ipynb` files
potentially clashing with paired scripts.
- Added support for obtaining the notebook language from its metadata,
enabling use of the "script" and "auto" format.
- Added support for automatic synchronization with paired files.
vim:tw=78:ts=8:noet:ft=help:norl: