Document how to filter nested metadata

Fix #416

CHANGELOG.md

@@ -3,9 +3,10 @@
 
 **Added**
 - Jupytext has a logo! Many thanks to Kyle Kelley for contributing the actual logo (#423), and to Chris Holdgraf for suggesting this (#260).
+- Nested metadata filtering is now supported! You can use this to rid of `jupytext_version` if you wish (#416).
 
 **Fixed**
-- Code cells in the Markdown format can contain triple backticks inside multiline strings (#419)
+- Code cells in the Markdown format can contain triple backticks inside multiline strings (#419).
 - Changes in the YAML header when running `jupytext --test` on text files are ignored (#414).
 
 1.3.2 (2020-01-08)

docs/using-server.md

@@ -27,7 +27,7 @@ If you want to pair a notebook to a python script in a subfolder named `scripts`
 
 Jupytext accepts a few additional options. These options should be added to the `"jupytext"` section in the metadata — use either the metadata editor or the `--opt/--format-options` argument on the command line.
 - `comment_magics`: By default, Jupyter magics are commented when notebooks are exported to any other format than markdown. If you prefer otherwise, use this boolean option, or is global counterpart (see below).
-- `notebook_metadata_filter`: By default, Jupytext only exports the `kernelspec` and `jupytext` metadata to the text files. Set `"jupytext": {"notebook_metadata_filter": "-all"}` if you want that the script has no notebook metadata at all. The value for `notebook_metadata_filter` is a comma separated list of additional/excluded (negated) entries, with `all` a keyword that allows to exclude all entries.
+- `notebook_metadata_filter`: By default, Jupytext only exports the `kernelspec` and `jupytext` metadata to the text files. Set `"jupytext": {"notebook_metadata_filter": "-all"}` if you want that the script has no notebook metadata at all. The value for `notebook_metadata_filter` is a comma separated list of additional/excluded (negated) entries, with `all` a keyword that allows to exclude all entries. Use dots to filter recursively the metadata. For instance, use `notebook_metadata_filter="-jupytext.text_representation.jupytext_version"` to remove the `jupytext_version` field in the `jupytext.text_representation` metadata.
 - `cell_metadata_filter`: By default, cell metadata `autoscroll`, `collapsed`, `scrolled`, `trusted` and `ExecuteTime` are not included in the text representation. Add or exclude more cell metadata with this option.
 
 ## Global configuration
@@ -70,6 +70,11 @@ c.ContentsManager.default_notebook_metadata_filter = "-all"
 c.ContentsManager.default_cell_metadata_filter = "-all"
 ```
 
+It is possible to filter nested metadata. For example, if you want to preserve the Jupytext metadata, but not the Jupytext version number, you can use:
+```python
+c.ContentsManager.default_notebook_metadata_filter = "-jupytext.text_representation.jupytext_version"
+```
+
 NB: All these global options (and more) are documented [here](https://github.com/mwouts/jupytext/blob/master/jupytext/contentsmanager.py).
 
 ## Can I edit a notebook simultaneously in Jupyter and in a text editor?

tests/test_contentsmanager.py

@@ -1596,3 +1596,32 @@ def nb(text):
     # so that we read cell inputs from the py file
     assert model_ipynb['last_modified'] < model_py['last_modified']
     assert model_py['last_modified'] < model_md['last_modified']
+
+
+@skip_if_dict_is_not_ordered
+@pytest.mark.parametrize('nb_file', list_notebooks('ipynb_py'))
+def test_filter_jupytext_version_information_416(nb_file, tmpdir):
+    tmp_py = str(tmpdir.join('notebook.py'))
+
+    cm = jupytext.TextFileContentsManager()
+    cm.root_dir = str(tmpdir)
+    cm.default_notebook_metadata_filter = "-jupytext.text_representation.jupytext_version"
+
+    # load notebook
+    notebook = jupytext.read(nb_file)
+    notebook.metadata['jupytext_formats'] = 'ipynb,py'
+    model = dict(type='notebook', content=notebook)
+
+    # save to ipynb and py
+    cm.save(model=model, path='notebook.ipynb')
+
+    assert os.path.isfile(tmp_py)
+
+    # read py file
+    with open(tmp_py) as fp:
+        text = fp.read()
+
+    assert '---' in text
+    assert 'jupytext:' in text
+    assert 'kernelspec:' in text
+    assert 'jupytext_version:' not in text